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About This Manual | ‘y 


The information contained in AS/400 Machine Interface Functional Reference has not been submitted to 
any formal IBM test and is distributed on an ‘as is’ basis without any warranty either expressed or 
implied. This manual is written for release 3 of AS/400 Vertical Licensed Integrated Code (VLIC) and 
may not discuss all the functions available on your AS/400 system. 


The AS/400 Machine Interface Functional Reference defines the AS/400 Machine Interface to 
instructions and exceptions. 


This manual may refer to products that are announced but are not yet available. 


Who Should Use This Manual 


This manual is intended for knowledgeable system programmers having substantial experience on 
AS/400 computer systems. 


What You Should Know 


The reader should know one more high level languages, assembly languages of other computers, and 
understand instruction set architectures. The reader would do well to study capability-based computer 
architectures. 


pete 


The reader should be familiar with AS/400 objects and their intended use. 


How This Manual Is Organized 
The AS/400 Machine Interface Functional Reference is organized into three parts: 


1. Basic Function Instructions 


These instructions provide a basic set of functions commonly needed by most programs executing 
on the machine. Because of the basic nature of these instructions, they tend to experience less 
change in their operation in different machine implementations than the extended function 
instructions. 


2. Extended Function Instructions 


These instructions provide an extended set of functions which can be used to control and monitor 
the operation of the machine. Because of the more complicated nature of these instructions, they 
are more exposed to changes in their operation in different machine implementations than the 
basic function instructions. 


3. Instruction Support Interfaces 


This part of the document defines those portions of the Machine Interface which provide support for 
functions or data used pervasively on all instructions. It discusses the exceptions and program 
objects which can be operated on by instructions. 
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Introduction 


Chapter 1. Introduction 


This chapter contains the following: 


¢ Detailed descriptions of the AS/400 machine interface instruction fields and the formats of these 
fields 


e A description of the format used in describing each instruction 


¢ A list of the terms in the syntax that define the characteristics of the operands 


You should read this chapter in its entirety before attempting to write instructions. 


Instruction Operands 


Each instruction requires from zero to four operands. Each operand may consist of one or more fields 
that contain either a null operand specification, an immediate data value, or a reference to an ODT 
object. The size of the operand field depends on the version of the program template. If the version 
number is 0, the size of the operand field is 2 bytes. If the version number is 1, the size of the operand 
field is 3 bytes. 


Null Operands: Certain instructions allow certain operands to be null. In general, a null operand 
means that some optional function of the instruction is not to be performed or that a default action is to 
be performed by the instruction. 


Immediate Operands: The value of this type of operand is encoded in the instruction operand. 
Immediate operands may have the following values: 


¢ Signed binary —representing a binary value of negative 4096 to positive 4095. 

e Unsigned binary —representing a binary value of 0 to 8191. 

¢ Byte string —representing a single byte value from hex 00 to hex FF. 

¢ Absolute instruction number—representing an instruction number in the range of 1 to 8191. 


¢« Relative instruction number—representing a displacement of an instruction relative to the instruc- 
tion in which the operand occurs. This operand value may identify an instruction displacement of 
negative 4096 to positive 4095. 


ODT Object References: This type of operand contains a reference (possibly qualified) to an 
object in the ODT. Operands that are ODT object references may be simple operands or compound 
operands. 


Simple Operands: The value encoded in the operand refers to a specific object defined in the ODT. 
Simple operands consist of a single 2-byte operand entry. 


Compound Operands: A compound operand consists of a primary (2-byte) operand and a series of 
one to three secondary (2-byte) operands. The primary operand is an ODT reference to a base object 
while the secondary operands serve as qualifiers to the base object. 


A compound operand may have the following uses: 


e Subscript references 


An individual element of a data object array, a pointer array, or an instruction definition list may be 
referenced with a subscript compound operand. The operand consists of a primary reference to 
the array and a secondary operand to specify the index value to an element of the array. 


© Copyright |BM Corp. 1991, 1993 1-1 


ra 


—— eee 


Introduction 


¢« Substring references 


A portion of a character scalar data object may be referenced as an instruction operand through a 
substring compound operand. The operand consists of a primary operand to reference the base 
string object and secondary references to specify the value of an index (position) and a value for 
the length of the substring. 


The length secondary operand field can specify whether to allow or not allow for a null substring 
reference (a length value of zero). 


e Explicit base references 


An instruction operand may specify an explicit override for the base pointer for a based data object 
or a based addressing object. The operand consists of a primary operand reference to the based 
object and a secondary operand reference to the pointer on which to base the object for this 
Operand. The override is in effect for the single operand. The displacement implicit in the ODT 
definition of the primary operand and the addressability contained in the explicit pointer are com- 
bined to provide an address for the operand. 


The explicit base may be combined with either the subscript or the substring compound operands to 
provide a based subscript compound operand or a based substring compound operand. 


Instruction Format Conventions Used In This Manual 


The user of this manual must be aware that not every instruction uses every field described in this 
section. Only the information pertaining to the fields that are used by an instruction is provided for 
each instruction. 


In this manual, each instruction is formatted with the instruction name followed by its base mnemonic. 
Following this is the operation code (op code) in hexadecimal and the number of operands with their 
general meaning. 


Example: 


ADD NUMERIC (ADDN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
1043 Sum Addend 1 Addend 2 


This information is followed by the operands and their syntax. See “Definition of the Operand Syntax” 
later in this chapter for a detailed discussion of the syntax of instruction operands. 


Example: 
Operand 1: Numeric variable scalar. 
Operand 2: Numeric scalar. 


Operand 3: Numeric scalar. 


ILE access 


A description of the parameters for Integrated Language Environment 
access to the instruction is given. See the corresponding ILE 
language reference manual for details as to how this information 
should be interpreted for a given language. 
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Description: A detailed description and a functional definition of the instruction is given. 


The terms are defined or fields in a template are described, they are highlighted as follows: term defi- } 
nition. When a term is referenced or a value of a field is refered to, it is highlighted as follows: term 
reference. 


Fields in a template are generally described in the same order as they are defined in the template. 
However, some fields are more appropriately described with other related field, so they may not 
appear in exact order. 


Authorization Required: A list of the object authorization required for each of the operands in the 
instruction or for any objects subsequently referenced by the instruction is given. 


Lock Enforcement: Describes the specification of the lock states that are to be enforced during exe- 
cution of the instruction. 
The following states of enforcement can be specified for an instruction: 

¢ Enforcement for materialization 


Access to a system object is allowed if no other process is holding a locked exclusive no read 
(LENR) lock on the object. In general, this rule applies to instructions that access an object for 
materialization and retrieval. 


e Enforcement for modification 


Access to a system object is allowed if no other process is holding a locked exclusive no read 
(LENR) or locked exclusive allow read (LEAR) lock. In general, this rule applies to instructions that 
modify or alter the contents of a system object. 


i . 
e Enforcement of object control | ) 
Access is prohibited if another process is holding any lock on the system object. In general, this 
rule applies to instructions that destroy or rename a system object. 
Limitations: These are the limits that apply to the functions performed by the instruction. 


Resultant Conditions: These are the conditions that can be set at the end of the standard operation in 
order to perform a conditional branch or set a conditional indicator. 


Exceptions: The “exceptions” sections contain a list of exceptions that can be caused by the 
instruction. Exceptions related to specific operands are indicated for each exception by the exception 
under the heading operand. An entry under the word, other, indicates that the exception applies to the 
instruction but not to a particular operand. 


A detailed description of exceptions is in Chapter 23, “Exception Specifications” on page 23-1. 


Definition of the operand syntax 
Syntax consists of the allowable choices for each instruction operand. The following are the common 
terms used in the syntax and the meanings of those terms: 
*« Numeric: Numeric attribute of binary, packed decimal, zoned-decimal, or floating-point 
¢ Character. character attribute 
¢ Scalar. - 
— Scalar data object that is not an array (see note 1) 


— Constant scalar object 
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— Immediate operand (signed or unsigned) 
— Element of an array of scalars (see notes 1 and 2) 


— Substring of a character scalar or a character scalar constant data 
object (see notes 1 and 3) 


Data Pointer Defined Scalar: 

— A scalar defined by a data pointer 

— Substring of a character scalar defined by a data pointer (see notes 1 and 3) 
Pointer: 

— Pointer data object that is not an array (see note 1) 

— Element of an array of pointers (see notes 1 and 2) 

— Space pointer machine object 

Array: An array of scalars or an array of pointers (see note 1) 


Variable Scalar. Same as scalar except constant scalar objects and immediate operand values are 
excluded. 


Data Pointer. A pointer data object that is to be used as a data pointer. 


— Ifthe operand is a source operand, the pointer storage form must contain a data pointer when 
the instruction is executed. 


— Ifthe operand is a receiver operand, a data pointer is constructed by the instruction in the 
specified area regardless of its current contents (see note 4). 


Space Pointer. A space pointer data object or a space pointer machine object. 
Space Pointer Data Object: A pointer data object that is to be used as a space pointer. 


— Ifthe operand is a source operand, the pointer storage form must contain a space pointer 
when the instruction is executed. 


— If the operand is a receiver operand, a space pointer is constructed by the instruction in the 
specified area regardless of its current contents (see note 4). 


System Pointer: a pointer data object that is to be used as a system pointer. 


— Ifthe operand is a source operand, the specified area must contain a system pointer when the 
instruction is executed. 


— Ifthe operand is a receiver operand, a system pointer is constructed by the instruction in the 
specified area regardless of its current contents (see note 4). 


Relative Instruction Number. Signed immediate operand. 
Instruction Number. Unsigned immediate operand. 
Instruction Pointer: A pointer data object that is to be used as an instruction pointer. 


— Ifthe operand is a source operand, the specified area must contain an instruction pointer when 
the instruction is executed. 


— If the operand is a receiver operand, an instruction pointer is constructed by the instruction in 
the specified area regardless of its current contents (see notes 4 and 5). 


Instruction Definition List Element: An entry in an instruction definition list that can be used as a 
branch target. A compound subscript operand form must always be used (see note 5). 
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Notes: 


1. An instruction operand in which the primary operand is a scalar or a pointer may also have an | 
operand form in which an explicit base pointer is specified. ) 


see “ODT Object References” earlier in this chapter for more information on compound operands. 


2. A compound subscript operand may be used to select a specific element from an array of scalars 
or from an array of pointers. 


See “ODT Object references” earlier in this chapter for more information on compound operands. 


3. A compound substring operand may be used to define a substring of a character scalar, or a char- 
acter constant scalar object. 


A compound substring operand that disallows a null substring reference (a length value of zero) 
may, unless precluded by the particular instruction, be specified for any operand syntactically 
defined as allowing a character scalar. A compound substring operand that allows a null substring 
reference may be specified for an operand syntactically defined as allowing a character scalar only 
if the instruction specifies that it is allowed. Whether a compound substring operand does or does 
not allow a null substring reference is controlled through the specification of the length secondary 
operand field. 


See “ODT Object References” earlier in this chapter for more information on compound operands. 


4. A compound subscript operand form may be used to select an element from an array of pointers to 
act as the operand for an instruction. See “ODT Object References” earlier in this chapter for 
more information on compound operands. 


5. Compound subscript forms are not allowed on branch target operands that are used for conditional 
branching. Selection of elements of instruction pointer arrays and elements of instruction definition 
lists may, however, be referenced for branch operands by the branch instruction. t 


Alternate choices of operand types and the allowable variations within each choice are indicated in the wa 
syntax descriptions as shown in the following example. 


Operand 7: Numeric variable scalar. 
Operand 2: Numeric scalar. 
Operand 3: Instruction number, branch point or instruction pointer.. 


Operand 1 must be variable scalar. Operands 1 and 2 must be numeric. Operand 3 can be an instruc- 
tion number, branch point or instruction pointer. 


When a length is specified in the syntax for the operand, character scalar operands must be at least 
the size specified. Any excess beyond that required by the instruction is ignored. 


Scalar operands that are operated on by instructions requiring 1-byte operands, such as pad values or 
indicator operands, can be greater than 1 byte in length; however, only the first byte of the character 
string is used. The remaining bytes are ignored by the instruction. 
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Basic Function Instructions 


These instructions provide a basic set of functions commonly needed by most programs executing on 
the machine. Because of the basic nature of these instructions, they tend to experience less change in 
their operation in different machine implementations than the extended function instructions. There- 
fore, it is recommended that, where possible, programs be limited to using just these basic function 
instructions to minimize the impacts which can arise in moving to different machine implementations. 
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This chapter describes all the instructions used for computation and branching. These instructions are 
arranged in alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, 
“Instruction Summary.” : 


Add Logical Character (ADDLC) ...... 2... 2. ee 2-3 
Ada: Numerig(ADON):. we. beard mas cade as B, S ee ae Bd a oh we et ee, ee ee ee & eed bok tee be RS 2-6 
PIV CINDY he ek, ee ty cad hn Aes ees Sa Sa AS ok des YR eg See ES eG es a a OS Se 2-10 
BANC AE):  A gece eek re te teh detec che iy ep ee ah See i eh ak i ee ee eae sa ae 2-13 
Clear Bitin- String (CERES) gs seit ae te hoard oe De ao te Be So 4S ee a et Sie Ss ek 2-15 
Compare Bytes Left-Adjusted (CMPBLA) .............0....0 000000000008 as 2-17 
Compare Bytes Left-Adjusted with Pad (CMPBLAP) ............... 0.000000 ee 2-19 
Compare Bytes Right-Adjusted (CMPBRA) ............. 0.000 ee eee eee ee ee 2-21 
Compare Bytes Right-Adjusted with Pad (CMPBRAP) ............ 0.00000 ee eee nee 2-23 
Compare Numeric Value (CMPNV) .... 0.0.0.0. 0 ee ee 2-25 
Compress Data {(CPRDATA): 64.0%: we de ees ob 5 oe Ce Ree ee RO heed eo a ER 2-28 
Compute Array index (CAN ..4.46%.4644 dewss a dee ee ay £4 db SE wees Beane ea hee 2-30 
Compute Math Function Using One Input Value (CMF1) ............ "ie uke Boe ate es 2-32 
Compute Math Function Using Two Input Values (CMF2) ................. 000008084 2-41 
Concatenate (CAT) ees 4e Hae ee Eee de Beemer and, Heed eb ge Sp weg , Mew, RR We Ae es 2-46 
Convert BSC to Character (CVTBC) ........0... 00.000 000002 eee 2-48 
Convert Character to BSC (CVTCB) .... 2... 2-52 
Convert Cnaracier tosHex(CViCH). coc cog na, ese eb ele ee A ge ee oe eee a ee ee Ee 2-55 
Convert Character to MRJE (CVTCM) ..... 2... 2-57 
Convert Character to Numeric (CVTCN) 1... 0.0.0. 00. 2-62 
Conven Character to: SNAICVICS)- c2004.6:2: 452 be ge See ee a eee ee Perk 2-65 
Convert Decimal Form to Floating-Point (CVTDFFP) .............. 2.000.000. eee 2-74 
Convert External Form to Numeric Value (CVTEFN) ...............0...0.0...02..0.00. 2-76 
Convert Floating-Point to Decimal Form (CVTFPDF) ............. 0.000 eee eee ene 2-79 
Convert Hex to Character (CVTHC) ........0.0.0.0 0.0.00 0002 cee ee 2-82 
Convert MRJE to Character (CVTMC) ......... 2.000000 0 eee 2-84 
Convert Numeric to Character (CVTNC) ...... 0... 00.0. ee ee 2-88 
Convert SNA to ‘Character (CVTISC) 22.43.4626 65 #45 wu CRW Ee wee eae eee ee SS 2-90 
Copy Bits Arithmetic (CPYBTA) ....... 0.0... 0.0.0. 2 eee 2-100 
Copy Bits: Logical (CPYBTL) 4. 6ee 22h a ce eae & OAD Ce HS eS ek wee Ew Rs 2-102 
Copy Bits with Left Logical Shift(CPYBTLLS) ..............0.... 2.2.0.0... 00048. 2-104 
Copy Bits with Right Arithmetic Shift (CPYBTRAS) ...................0-20.00-. 2-106 
Copy Bits with Right Logical Shift (CPYBTRLS) ...................2..0. 00200404 2-108 
Copy Bytes Left-Adjusted (CPYBLA) ........... 0.0000 0 eee ee 2-110 
Copy Bytes Left-Adjusted with Pad (CPYBLAP) ............ 2... 002 eee ee ees 2-112 
Copy Bytes Overlap Left-Adjusted (CPYBOLA) ............. 2... 2 eee ee ee eee 2-114 
Copy Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) ...................00.4. 2-116 
Copy Bytes Repeatedly (CPYBREP) ....... 0... 0. cee ee 2-118 
Copy Bytes Right-Adjusted (CPYBRA) .........0. 0.0.0 2 ee 2-120 
Copy Bytes Right-Adjusted with Pad (CPYBRAP) ............. 0.0. eee eee, 2-122 
Copy Bytes to Bits Arithmetic (CPYBBTA) ........... 0... 00 ee 2-124 
Copy Bytes to Bits Logical (CPYBBTL) ............0.. 00.0002 2 bee es 2-126 
Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) ................... 2-128 
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Copy Hex Digit Numeric to Numeric (CPYHEXNN) .........0.0000 002000000 ee 2-132 
Copy Hex Digit Numeric to Zone (CPYHEXNZ) ..........0 000.0000 2 ec 2-134 
Copy Hex Digit Zone To Numeric (CPYHEXZN) .........0 0.00000 000 eee ee 2-136 
Copy Hex Digit Zone To Zone (CPYHEXZZ) ......... 0.0.0.0. 00 2 ee ee 2-138 
Copy Numeric Value (CRPYNV): <<4644¢24 4 o6 9 ob G 4.4.4 es ow oS SORA BEAMS Shee 2-140 
Decompress Data (DCPDATA) ...... 0.0.0.0 00 0 2-143 
DIVIGG IS Ben tae! Aus wat aie chip tater ee Oe tone, Oe aed aus ba oe i we ae eat oe ae es ae OR ek a 2-146 
Divide with Remainder (DIVREM) ...........0.0... 02000000. cee ee ee 2-150 
GC CE IOUT ck xc: tn tes er each ote Gs ts Gy el he eB cd eh AS ne Ee to Bet Bee eee et 2-154 
BxChande BYVICS{EXGMOY)” 4.9.8. te Sone ae Se es BR Ee he SG Ob ee ee Sekt aes 2-162 
EXCIUSIVe OFUXKOR):-. << s-uy Swe 2S Bs Bes eoerh 6 hee SS ee se Be eee 2-164 
Extended: Character Scan (ECSCAN). «2.2 2 4-ceS ce date Ged eS OS See OL EE es dhe 2-167 
Extract Exponent (EXTREXP): .< 4.4..24-4%4.8 66468402 ete ae eden hee AR Ow EE EES 2-171 
Extract Magnitude (EXTRMAG) .... 2... 2... ee 2-174 
VIC OIY OME us, 8. ed. ch cn ce Meh see oat  k oe Sh ted ee ee i Ase ee eee 2-177 
Negalie (NEG) .422 box din rtat eth eee tice ¢ Bae hee ee wee Cet Ss eee ee ee 2-181 
NGECINOT)- Sirus Ped de teat rh cue et a oh ad oh See ee ices G Seah oe ree sg ones ine, ee ie, GOR 2-184 
Or(OR). 228444853448 0e tee hoe es Bohs 4 eb le © oe BO ee ee fob 2-187 
ReEMaGINGCrIREM) Ace oar de eu oO eS, BRS ae a Reh en we eee Be ER Se SoS 2-190 
Scdle(SCAVE): 4.6 Ge oe SAE ee eRe eee ee eee ee wees 2-194 
BEAIPNSCAIN otk less yeah ea vere a ae cca de ee ee Ee tang Oo a ae Se @ 2-198 
scan with Control (SCANWC) «02 4.04 686 bw wei eee WERE Se ee eee wee 2-201 
SCaren(SEARCh).; sia. 35 4 head OO ee ee ee GAO & Sk SO es Se le Se 2-209 
SeECBIUiIn-StuiIng: (SETBIS) 44.23 vee8ae ee eee ew Oe Se Ble eee Se ek Se 2-212 
Set Instruction Pointer (SETIP) .............. 000 eee eee eee “Wide Ws Hen hdd lade Ga 2-214 
Store and Set Computational Attributes (SSCA) ...........00.. 2.2.0.0 02.000 ee eee 2-216 
Subtract Logical ‘Cnaracter (SUBLC) <2 ¢.4:.5.2h 43 ee erect Sema aE HEE GR RMS Ew Ss 2-220 
subtract NUmerne(SUBN): 25 .hé458 eee eee EE ER oe SA SS BELG oe ps 2-223 
Test and Replace Characters (TSTRPLC) .......... 0.0... cee ee 2-227 
Test BiPin-String (I SIBis))). 605 hus ea we Re eee oe ea ea WY ed go ne SES es 2-229 
Test Bits Under Mask (TSTBUM) ..... 2... 2... ee 2-231 
TRANS ate OMCATE)\.. Qos & BM Sah eh ee tak Ge bg Sete ee ee Pe a HO OS, ee A 2-233 
Translate with Table (XLATEWT) ...... 2.0... 00 2 ee 2-235 
Translate with Table and DBCS Skip (XLATWTDS) ............0..... 0020082 ae 2-237 
Tom: LenGinstURIML):. «2S << ae ee Dae ee Ged wk ee Oe ON BORE ee RES 2-240 
VEY (VERRIER I. 22:S:0il eth in ee eck Ge ee andar Soak th eae Se Be Se See Be Be Be & ne 2-242 
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Add Logical Character (ADDLC) 


Add Logical Character (ADDLC) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-7 | 
ADDLC Sum Addend 1 Addend 2 

1023 

ADDLCI Indicator Sum Addend 1 Addend 2 Indicator targets 
1823 options 

ADDLCB Branch options Sum Addend 1 Addend 2 Branch targets 
1€23 


Operand 1: Character variable scalar (fixed-length). 
Operand 2: Character scalar (fixed-length). 
Operand 3: Character scalar (fixed-length). 


Operand 4-7: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
ADDLCS Sum/Addend 1 Addend 2 

1123 

ADDLCIS Indicator options Sum/Addend 1 Addend 2 Indicator targets 
1923 

ADDLCBS Branch options Sum/Addend 1 Addend 2 Branch targets 
1D23 


Operand /: Character variable scalar (fixed-length). 
Operand 2: Character scalar (fixed-length). 


Operand 3-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The unsigned binary value of the addend 1 operand is added to the unsigned binary. 
value of the addend 2 operand and the result is placed in the sum operand. 


Operands 1, 2, and 3 must be the same length; otherwise, the Create Program instruction signals an 
invalid operand length (hex 2A0A) exception. The length can be a maximum of 256 bytes. 


The addition operation is performed according to the rules of algebra. The result value is then placed 
(left-adjusted) in the receiver operand with truncating or padding taking place on the right. The pad 
value used in this instruction is a byte value of hex 00. 
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If operands overlap but do not share ail of the same bytes. results of operations performed on these 
operands are not predictable. If overlapped operands share all of the same bytes. the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


Resultant Conditions: The logical sum of the character scalar operands is: 


zero with no carry out of the leftmost bit position 
not-zero with no carry 
zero with carry 


not-zero with carry. 


Exceptions 


Exception 1 2 3 Other 


06 


08 


10 


20 


22 


24 


2C 


2E 


Addressing 

01 Spacing addressing violation 
02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x KK XK 
x KK XK 
x KK OK 


Argument/parameter 


01 Parameter reference violation Xx Xx D4 


Damage encountered 
04 System object damage state X X Xx X 
44 Partial system object damage X X X X 


Machine-dependent exception 


03 Machine storage limit exceeded X 


Machine support 
02 Machine check X 
03 Function check X 


Object access 

01 Object not found X X X 
02 Object destroyed 
03 Object suspended X X X 


08 object compressed X 


~* 
~< 
~x< 


Pointer specification 
01 Pointer does not exist X X X 
02 Pointer type invalid X xX X 


Program execution 


04 Invalid branch target Xx 


Resource control limit 


01 user profile storage limit exceeded xX 
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Exception 
36 Space management 


01 space extension/truncation 


Add Logical Character (ADDLC) 


Operands 
1 2 3 Other 
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Add Numeric (ADDN) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-7] 
ADDN Sum Addend Augend 

1043 

ADDNR Sum Addend Augend 

1243 

ADDNI Indicator Sum Addend Augend Indicator targets 
1843 options 

ADDNIR Indicator Sum Addend Augend Indicator targets 
1A43 options 

ADDNB Branch options Sum Addend Augend Branch targets 
1043 

ADDNBR Branch options Sum Addend Augend Branch targets 
1E43 


Operand 1: Numeric variable scalar 
Operand 2: Numeric scalar 
Operand 3: Numeric scalar 


Operand 4-7: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
ADDNS Sum/Addend Augend 

1143 

ADDNSR Sum/Addend Augend 

1343 

ADDNIR Indicator options Sum/Addend Augend Indicator targets 
1943 

ADDNISR Indicator options Sum/Addend Augend Indicator targets 
1B43 

ADDNBS Branch options Sum/Addend Augend Branch targets 
1D43 

ADDNBSR Branch options Sum/Addend Augend Branch targets 
1F43 


Operand 71: Numeric variable scalar 
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Operand 2: Numeric scalar 


Operand 3-6: ) 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Caution: |f operands overlap but do not share all of the same bytes, results of operations performed 
on these operands are not predictable. If overlapped operands share all of the same bytes, the results 
are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


Description: The Sum is the result of adding the Addend and Augend. 
Operands can have floating-point, packed or zoned decimal, signed or unsigned binary type. 
Source operands are the Addend and Augend. The receiver operand is the Sum. 


lf operands are not of the same type, addends are converted according to the following rules: 
1. If any one of the operands has floating point type, addends are converted to floating point type. 


2. Otherwise, if any one of the operands has zoned or packed decimal type, addends are converted to 
packed decimal. 


3. Otherwise, the binary operands are converted to a like type. Note: unsigned binary(2) scalars are 
logically treated as signed binary(4) scalars. 


Addend and Augend are added according to their type. Floating point operands are added using ~<A 
floating point addition. Packed decimal addends are added using packed decimal addition. Unsigned 

binary addition is used with unsigned addends. Signed binary addends are added using two’s comple- 

ment binary addition. 


Better performance can be obtained if all operands have the same type. Signed and unsigned binary 
additions execute faster than either packed decimal or floating point additions. 


Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. 


For a decimal operation, alignment of the assumed decimal point takes place by padding with 0’s on 
the right end of the addend with lesser precision. 


Floating-point addition uses exponent comparison and significand addition. Alignment of the binary 
point is performed, if necessary, by shifting the significand of the value with the smaller exponent to 
the right. The exponent is increased by one for each binary digit shifted until the two exponents agree. 


The operation uses the lengths and the precision of the source and receiver operands to calculate 
accurate results. Operations performed in decimal are limited to 31 decimal digits in the intermediate 
result. 


The addition operation is performed according to the rules of algebra. 


The result of the operation is copied into the sum operand. If this operand is not the same type as that 

used in performing the operation, the resultant value is converted to its type. If necessary, the ; 
resultant value is adjusted to the length of the sum, aligned at the assumed decimal point of the sum 3 
operand, or both before being copied. If nonzero digits are truncated on the left end of the resultant 

value, a size (hex OCOA) exception is signaled. 
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When the target of the instruction is signed or unsigned binary size, exceptions can be suppressed. 


For the optional round form of the instruction, specification of a floating-point receiver operand is 
invalid. 


For fixed-point operations, if nonzero digits are truncated off the left end of the resultant value, a size 
(hex OCOA) exception is signaled. 


For floating-point operations involving a fixed-point receiver field, if nonzero digits would be truncated 
off the left end of the resultant value, an invalid floating-point conversion (hex OCOC) exception is sig- 
naled. 


For a floating-point sum, if the exponent of the resultant vaiue is either too large or too small to be 
represented in the sum field, the floating-point overflow (hex OCOB) and floating-point underflow (hex 
0CO7) exceptions are signaled, respectively. 


If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 
Resultant Conditions 

e Positive - The algebraic value of the numeric scalar sum operand is positive. 

e Negative - The algebraic value of the numeric scalar sum operand is negative. 

e Zero - The algebraic value of the numeric scalar sum operand is zero. 


e Unordered - The value assigned a floating-point sum operand is NaN. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Spacing addressing violation 
02 Boundary alignment 


03 Range 


x KX K XK 
x KK K 
x KK KK 


06 Optimized addressability invalid 


08 Argument/parameter 
01 Parameter reference violation X X X 
0c Computation 
02 Decimal data X X 
03 Decimal point alignment X X 
06 Floating-point overflow X 
07 Floating-point underflow X 
09 Floating-point invalid operand X X X 
0A Size X 
0C Invalid floating-point conversion X 
OD Floating-point inexact result X 
10 Damage encountered 
04 System object damage state X X X X 
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Exception 


1C 


20 


22 


24 


2C 


2E 


36 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Add Numeric (ADDN) 


Operands 
1 2 Other 
X X X X 


w 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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And (AND) 


And (AND) 

Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 
AND Receiver Source 1 Source 2 

1093 

ANDI Indicator Receiver Source 1 Source 2 Indicator targets 
1893 options 

ANDB Branch options Receiver Source 1 Source 2 Branch targets 
1C93 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 
Operand 3: Character scalar or numeric scalar. 


Operand 4-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-4] 
ANDS Receiver/Source 1 Source 2 

1193 

ANDIS Indicator options Receiver/Source 1 Source 2 Indicator targets 
1993 

ANDBS Branch options Receiver/Source 1 Source 2 Branch targets 
1D93 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 


Operand 3-4: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 
Description: The Boolean AND operation is performed on the string values in the source operands. 
The resulting string is placed in the receiver operand. The operands may be character or numeric 


scalars. They are both interpreted as bit strings. Substringing is supported for both character and 
numeric operands. 


The length of the operation is equal to the length of the longer of the two source operands. The 
shorter of the two operands is logically padded on the right with hex 00 values. This assigns hex 00 
values to the results for those bytes that correspond to the excess bytes of the longer operand. 

The bit values of the result are determined as follows: 
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And (AND) 


Source 1 Bit Source 2 Bit Result Bit 
0 0 0 
0 1 0 
1 0 0 


1 1 1 


The result value is then placed (left-adjusted) in the receiver operand with truncating or padding taking 
place on the right. The pad value used in this instruction is a byte value of hex 00. 


lf operands overlap but do not share all of the same bytes, results of operations performed on these 
operands are not predictable. If overlapped operands share all of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 

specified for operands 1, 2, and 3. The effect of specifying a null substring reference for either or both 
of the source operands is that the result is all zero and instruction’s resultant condition is zero. When 

a null substring reference is specified for the receiver, a result is not set and the instruction’s resultant 
condition is zero regardless of the values of the source operands. 


When the receiver operand is a numeric variable scalar, it is possible that the result produced will not 
be a valid value for the numeric type. This can occur due to padding with hex 00, due to truncation, or 
due to the resultant bit string produced by the instruction. The instruction completes normally and 
signals no exceptions for these conditions. 


Resultant Conditions 


e Zero - The bit value for the bits of the scalar receiver operand is either all zero or a null substring 
reference is specified for the receiver. 


e Not zero - The bit value for the bits of the scalar receiver operand is not all zero. 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 Spacing addressing violation X X X 

02 Boundary alignment X X X 

03 Range X X X 

06 Optimized addressability invalid X X X 
08 Argument/parameter 

01 Parameter reference violation X X X 
10 Damage encountered 

04 System object damage state X X X X 

44 Partial system object damage X X X X 
1C Machine-dependent exception 

03 Machine storage limit exceeded X 
20 Machine support 
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Exception 


22 


24 


2C 


2E 


36 


02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


And (AND) 


Operands 

1 2 3 Other 
X 
X 

X X X 

X X X 

X X X 
X 

X X X 

X X X 
X 
X 
X 
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Branch (B) 


Op Code (Hex) . Operand 1 


1011 


Branch target 


Branch (B) 


Operand 7: |nstruction number, relative instruction number, branch point, instruction pointer, or 
instruction definition list element. 


Description: Control is unconditionally transferred to the instruction indicated in the branch target 
operand. The instruction number indicated by the branch target operand must be within the instruction 


stream containing the branch instruction. 


The branch target may be an element of an array of instruction pointers or an element of an instruction 
definition list. The specific element can be identified by using a compound subscript operand. 


Exceptions 


Exception 


06 


08 


10 


1C 


20 


22 


24 


2C 


2E 


Addressing 
01 Spacing addressing violation 
02 Boundary alignment violation 


03 Range 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


Operand 

1 Other 

X 

X 

X 

X 

X X 

X X 
X 
X 
X 

X 

X 

X 
X 

X 

X 

X 
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Branch (B) 
Operand 
Exception 1 Other 
{ 01 user profile storage limit exceeded X 
36 Space management 
01 space extension/truncation X 


Chapter 2. Computation and Branching Instructions 2-14 


Clear Bit in String (CLRBTS) 


Clear Bit in String (CLRBTS) 


Op Code (Hex) Operand 1 Operand 2 Za 
102E Receiver Offset 


Operand ?: Character variable scalar (fixed length) or numeric variable scalar. 

Operand 2: Binary scalar. 

Description: Clears the bit of the receiver operand as indicated by the bit offset operand. 
The selected bit from the receiver operand is set to a value of binary 0. 


The receiver operand can be character or numeric. The leftmost bytes of the receiver operand are 
used in the operation. The receiver operand is interpreted as a bit string with the bits numbered left to 
right from 0 to the total number of bits in the string minus 1. 


The receiver cannot be a variable substring. 


The offset operand indicates which bit of the receiver operand is to be cleared, with a offset of zero 
indicating the leftmost bit of the leftmost byte of the receiver operand. 


If a offset value less than zero or beyond the length of the string is specified, a sca/ar value invalid (hex 
3203) exception is signaled. 


Exceptions 


Exception 1 2 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment violation 
03 Range 
06 Optimized addressability invalid 


x KK XK 
x KK RK 


08 Argument/parameter 


01 Parameter reference violation ».4 ».4 


10 Damage encountered 
04 System object damage state X 
44 Partial system object damage X 


1c Machine-dependent exception 


03 Machine storage limit exceeded Xx 


20 Machine support 
02 Machine check X 
03 Function check X 


22 Object access 


02 Object destroyed X X ) 
03 Object suspended X X 


08 object compressed x 
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L 


Exception 


24 


2A 


2E 


32 


36 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program creation 

06 Invalid operand type 

07 Invalid operand attribute 

08 Invalid operand value range 
0A Invalid operand length 

OC Invalid operand odt reference 


0D Reserved bits are not zero 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


03 Scalar value invalid 


Space management 


01 space extension/truncation 


Clear Bit in String (CLRBTS) 


Operands 
1 2 Other 


>< 


x KK KK OK 
x KK KK OK 
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Compare Bytes Left-Adjusted (CMPBLA) 


Compare Bytes Left-Adjusted (CMPBLA) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 (4, 5] - 
CMPBLAB Branch options Compare Compare Branch targets 

1CC2 operand 1 operand 2 

CMPBLAI Indicator options Compare Compare Indicator targets 

18C2 operand 1 operand 2 


Operand 7: Numeric scalar or character scalar. 
Operand 2: Numeric scalar or character scalar. 


Operand 3 [4, 5]: 
¢ Branch Form-|nstruction number, relative instruction number, branch point, or instruction pointer. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: This instruction compares the logical string vaiues of two left-adjusted compare oper- 
ands. The logical string value of the first compare operand is compared with the logical string value of 
the second compare operand (no padding done). Based on the comparison, the resulting condition is 
used with the extender field to: 


¢ Transfer contro! conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


e Assign a value to each of the indicator operands (indicator form). 
t 


The compare operands can be either character or numeric. Any numeric operands are interpreted as } 
logical character strings. 


The compare operands are compared byte by byte, from left to right with no numeric conversions per- 
formed. The length of the operation is equal to the length of the shorter of the two compare operands. 
The comparison begins with the leftmost byte of each of the compare operands and proceeds until all 
bytes of the shorter compare operand have been compared or until the first unequal pair of bytes is 
encountered. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for either or both 
compare operands is that the instruction’s resultant condition is equal. 


Resultant Conditions: The scalar first compare operand’s string value is one of the following as com- 
pared to the second compare operand. 


¢« higher 
e« lower 
¢ equal 
Exceptions 
Operands 
Exception 1 2 3 [4, 5] Other 
06 Addressing 
01 Spacing addressing violation X X X - | 
02 Boundary alignment X xX X 
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Exception 


08 


10 


1C 


20 


22 


24 


2C 


2E 


36 


03 Range 
06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Branch target invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Compare Bytes Left-Adjusted (CMPBLA) 


Operands 

1 2 3 [4, 5] Other 

X X X 

X X X 

X X X 

X X X X 

X X X X 
X 
X 
X 

X X X 

X X X 

X X X 
X 

X X X 

X X X 
X 
X 
X 
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Compare Bytes Left-Adjusted with Pad (CMPBLAP) 


Compare Bytes Left-Adjusted with Pad (CMPBLAP) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand 4 [5, 6] 
CMPBLAPB Branch options Compare Compare Pad Branch targets 
1CC3 operand 1 operand 2 

CMPBLAPI Indicator Compare Compare Pad Indicator targets 
18C3 options operand 1 operand 2 


Operand 1: Numeric scalar or character scalar. 
Operand 2: Numeric scalar or character scalar. 
Operand 3: Numeric scalar or character scalar. 


Operand 4 [5, 6]: 
¢ Branch Form-instruction number, relative instruction number, branch point, or instruction pointer. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: This instruction compares the logical string values of two left-adjusted compare operands 
(padded if needed). The logical string value of the first compare operand is compared with the logical 
string value of the second compare operand. Based on the comparison, the resulting condition is used 
with the extender field to: ; 


¢ Transfer control conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


¢ Assign a value to each of the indicator operands (indicator form). 


The compare operands can be either character or numeric. Any numeric operands are interpreted as 
logical character strings. 


The compare operands are compared byte by byte, from left to right with no numeric conversions 
being performed. 


The length of the operation is equal to the length of the longer of the two compare operands. The 
shorter of the two compare operands is logically padded on the right with the 1-byte value indicated in 
the pad operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. The 
comparison begins with the leftmost byte of each of the compare operands and proceeds until all the 
bytes of the longer of the two compare operands have been compared or until the first unequal pair of 
bytes is encountered. All excess bytes in the longer of the two compare operands are compared to 
the pad value. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for one of the 
compare operands is that the other compare operand is compared with an equal length string of pad 
character values. When a null substring reference is specified for both compare operands, the 
resultant condition is equal. 


Substring operand references that allow for a null substring reference (a length value of zero) may not 
be specified for operand 3. 
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snd 
' 


Compare Bytes Left-Adjusted with Pad (CMPBLAP) 


Resultant Conditions: The scalar first compare operand’s string value is one of the following as com- 
pared to the second compare operand. 


e higher 


lower 


* equal 


Exceptions 


Exception 


06 


08 


10 


20 


22 


24 


2C 


2E 


36 


Addressing 

01 Spacing addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Branch target invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Operands 
1 2 3 4 (5, 6] Other 


x KK XK 
x KK XK 
x KK XK 
x KK OK 


X X X X X 
X X X X X 
X 
X 
X 


x< 
x 
x 
x 


X 
X X X X 
X X X X 
X 
X 
X 
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Compare Bytes Right-Adjusted (CMPBRA) 


Compare Bytes Right-Adjusted (CMPBRA) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 (4, 5] 
CMPBRAB Branch options Compare Compare Branch targets 
1CC6 operand 1 operand 2 

CMPBRAI Indicator options Compare Compare Indicator targets 
18C6 operand 1 operand 2 


Operand 1: Numeric scalar or character scalar. 
Operand 2: Numeric scalar or character scalar. 


Operand 3 [4, 5]: 
¢ Branch Form-\instruction number, relative instruction number, branch point, or instruction pointer. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: This instruction compares the logical string values of two right-adjusted compare oper- 
ands. The logical string value of the first compare operand is compared with the logical string value of 
the second compare operand (no padding done). Based on the comparison, the resulting condition is 
used with the extender field to: 


e Transfer control conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


e Assign a value to each of the indicator operands (indicator form). 


The compare operands can be either string or numeric. Any numeric operands are interpreted as 
logical character strings. 


The compare operands are compared byte by byte, from left to right with no numeric conversions per- 
formed. The length of the operation is equal to the length of the shorter of the two compare operands. 
The comparison begins with the leftmost byte of each of the compare operands and proceeds until all 
bytes of the shorter compare operand have been compared or until the first unequal pair of bytes is 
encountered. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for either or both 
compare operands is that the instruction’s resultant condition is equai. 


Resuitant Conditions: The scalar first compare operand’s string value is one of the following as com- 
pared to the second compare operand. 


e higher 
° lower 
e equal 
Exceptions 
Operands 
Exception 1 2 3 (4, 5] Other 
06 Addressing 
01 Spacing addressing violation X X X 
02 Boundary alignment violation X X X 
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ey 


Exception 


08 


1C 


20 


22 


24 


2C 


2E 


36 


03 Range 
06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed — 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Branch target invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Compare Bytes Right-Adjusted (CMPBRA) 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 


3 [4, 5] 


< 


Other 
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Compare Bytes Right-Adjusted with Pad (CMPBRAP) 


Compare Bytes Right-Adjusted with Pad (CMPBRAP) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand 4 (5, 6] 


CMPBRAPB Branch options Compare Compare Pad Branch targets 
1CC7 operand 1 operand 2 

CMPBRAPI Indicator Compare Compare Pad Indicator targets 
18C7 options operand 1 operand 2 


Operand 7: Numeric scalar or character scalar. 
Operand 2: Numeric scalar or character scalar. 
Operand 3: Numeric scalar or character scalar. 


Operand 4 [5, 6]: 
¢ Branch Form-instruction number, relative instruction number, branch point, or instruction pointer. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: This instruction compares the logical string values of the right-adjusted compare oper- 
ands (padded if needed). The logical string value of the first compare operand is compared with the 
logical string value of the second compare operand. Based on the comparison, the resulting condition 
is used with the extender field to: 


e Transfer control conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


e Assign a value to each of the indicator operands (indicator form). 


The compare operands can be either character or numeric. Any numeric operands are interpreted as 
logical character strings. 


The compare operands are compared byte by byte, from left to right with no numeric conversions per- 
formed. 


The length of the operation is equal to the length of the longer of the two compare operands. The 
shorter of the two compare operands is logically padded on the left with the 1-byte value indicated in 
the pad operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. The 
comparison begins with the leftmost byte of the longer of the compare operands. Any excess bytes 
(on the left) in the longer compare operand are compared with the pad value. All other bytes are 
compared with the corresponding bytes in the other compare operand. The operation proceeds until 
all bytes in the longer operand are compared or until the first unequal pair of bytes is encountered. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for one of the 
compare operands is that the other compare operand is compared with an equal length string of pad 
character values. When a null substring reference is specified for both compare operands, the 
resultant condition is equal. 


Substring operand references that allow for a null substring reference (a length value of zero) may not 
be specified for operand 3. 
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Compare Bytes Right-Adjusted with Pad (CMPBRAP) 


Resultant Conditions: The scalar first compare operand’s string value is one of the following as com- 
pared to the second compare operand. 


¢ higher 


lower 


* equal 


Exceptions 


Exception 


06 


08 


10 


ic 


20 


22 


24 


2C 


2E 


36 


Addressing 

01 Spacing addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Branch target invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Operands 

1 2 3 4 [5, Other 
6] 

X X X X 

X X X X 

X X X xX 

X X X X 


X X . X X X 
X X X X X 
X 
X 
X 


~ 
*< 
~ 
x 


X 
X X X X 
X X X X 
X Xx 

X 

X 
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Compare Numeric Value (CMPNV) 


Compare Numeric Value (CMPNV) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 ([4-6| 
CMPNVB Branch options Compare Compare Branch targets 
1C46 operand 1 operand 2 

CMPNVI Indicator options Compare Compare Indicator targets 
1846 Operand 1 operand 2 


Operand ?: Numeric scalar. 
Operand 2: Numeric scalar. 


Operand 3 [4-6]: 
* Branch Form-|nstruction number, relative instruction number, branch point, or instruction pointer. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The numeric value of the first compare operand is compared with the signed or unsigned 
numeric value of the second compare operand. Based on the comparison, the resulting condition is 
used with the extender field to: 


e¢ Transfer control conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


e Assign a value to each of the indicator operands (indicator form). 


For a decimal operation, alignment of the assumed decimal point takes place by padding with 0’s on 
the right end of the compare operand with lesser precision. 


Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. 


When both operands are signed numeric or both are unsigned numeric, the length of the operation is 
equal to the length of the longer of the two compare operands. 


When one operand is signed numeric and the other operand unsigned numeric, the unsigned operand 
is converted to a signed value with more precision than its current size. The length of the operation is 
equal to the length of the longer of the two compare operands. A negative signed numeric value will 
always be less than a positive unsigned value. 


Floating-point comparisons use exponent comparison and significand comparison. For a denormalized 
floating-point number, the comparison is performed as if the denormalized number had first been nor- 


malized. 


For floating-point, two values compare unordered when at least one comparand is NaN. Every NaN 
compares unordered with everything including another NaN value. 


Floating-point comparisons ignore the sign of zero. Positive zero always compares equal with nega- 
tive zero. 


A floating-point invalid operand (hex OCO9) exception is signaled when two floating-point values 
compare unordered and no branch or indicator option exists for any of the unordered, negation of 
unordered equal, or negation of equal resultant conditions. 


When a comparison is made between a floating-point compare operand and a fixed-point decimal 
compare operand that contains fractional digit positions, a floating-point inexact result (nex OCOD) 
exception may be signaled because of the implicit conversion from decimal to floating-point. 
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Resultant Conditions 


¢ High-The first compare operand has a higher numeric value than the second compare operand. 


Compare Numeric Value (CMPNV) 


Low-The first compare operand has a Jower numeric value than the second compare operand. 


¢« Equal-The first compare operand has a equal numeric value than the second compare operand. 


* Unordered-The first compare operand is unordered compared to the second compare operand. 


Exceptions 


Exception 


06 


08 


0c 


1¢ 


20 


22 


24 


2C 


2E 


Addressing 

01 Spacing addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Computation 

02 Decimal data 

03 Decimal point alignment 

09 Floating-point invalid operand 


OD Floating-point inexact result 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 
02 Object destroyed 
03 Object suspended 


08 abject compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Branch target invalid 


Resource control limit 


1 2 3 [4-6] Other 


X X X 
X X X 
X X X 
X X X 
X X X 
X X 
X X 
X X 
X 
X X X X 
X X X X 
X 
X 
X 
X X X 
X X X 
xX X XK 
X 
X X X 
X X X 
X 
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Compare Numeric Value (CMPNV) 


Operands 
Exception 1 2 3 [4-6] Other 
01 user profile storage limit exceeded X 
36 Space management 
01 space extension/truncation X 
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Compress Data (CPRDATA) 


Op Code (Hex) Operand 1 


1041 Compress Data 
template 


Operand ?f: Space pointer. 


ILE access 


CPRDATA ( 
compress data template : space pointer 
) 


Description: The instruction compresses user data of a specified length. Operand 1 identifies a tem- 
plate which identifies the data to be compressed. The template also identifies the result space to 
receive the compressed data. 


The Compress Data template must be aligned on a 16-byte boundary. The format is as follows: 


e Source length Bin(4) 
e Result area length Bin(4) 
¢ Actual result length - ' Bin(4)* 
e Compression algorithm Bin(2) 
1 = Simple TERSE algorithm 
2 = IBM LZ1 algorithm 
« Reserved (binary 0) Char(18) 
e Source space pointer Space pointer 
e Result space pointer Space pointer 


Note: The input value associated with template entries annotated with an asterisk (*) are ignored by 
the instruction; these fields are updated by the instruction to return information about instruction 
execution. 


The data at the location specified by the source space pointer for the length specified by the source 
length is compressed and stored at the location specified by the result space pointer. The actual result 
length is set to the number of bytes in the compressed result. The source data is not modified. 


The value of both the source length field and result area length field must be greater than zero. Ifthe 
compressed result is longer than the result area (as specified by the result area length), the com- 
pression is stopped and only result area length bytes are stored. 


The compression algorithm field specifies the algorithm used to compress the data. The /BM LZ? algo- 
rithm tends to produce better compression on shorter input strings than the simple TERSE algorithm. 
The algorithm choice is stored in the compressed output data so the Decompress Data instruction will 
automatically select the correct decompression algorithm. 


Only scalar (non-pointer) data is compressed, so any pointers in the data to be compressed are 
destroyed in the output of the Decompress Data instruction. 
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Authorization Required 


« None 


Lock Enforcement 


« None 


Exceptions 
Operands 
Exception 1 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KX KK 


06 optimized addressability invalid 


08 Argument/Parameter 
01 Parameter reference violation X 
10 Damage encountered 


44 partial system object damage X X 


1c Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check 4 
03 function check »4 


22 Object access 
02 object destroyed X X 
03 object suspended X X 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X X 


02 pointer type invalid X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X X 


38 Template specification 


01 template value invalid X 


44 Domain 


01 object domain error X 
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Compute Array Index (CAI) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
1044 Array index Subscript A Subscript B Dimension 


Operand 1: Binary(2) variable scalar. 

Operand 2: Binary(2) scalar. 

Operand 3: Binary(2) scalar. 

Operand 4: Binary(2) constant scalar object or immediate operand. 


Description: This instruction provides the ability to reduce multidimensional array subscript values 
into a single index value which can then be used in referencing the single-dimensional arrays of the 
system. This index value is computed by performing the following arithmetic operation on the indi- 
cated operands. 


Array Index = Subscript A + ((Subscript B-1) X Dimension) 


The numeric value of the subscript B operand is decreased by 1 and multiplied by the numeric value of 
the dimension operand. The result of this multiplication is added to the subscript A operand and the 
sum is placed in the array index operand. 


All the operands must be binary with any implicit conversions occurring according to the rules of arith- 
metic operations. The usual rules of algebra are observed concerning the subtraction, addition, and 
multiplication of operands. 


This instruction provides for mapping multidimensional arrays to single-dimensional arrays. The ele- 
ments of an array with the dimensions (d1, d2, d3, ..., dn) can be defined as a single-dimensional array 
with d1*d2*d3*...“dn elements. To reference a specific element of the multidimensional array with sub- 
scripts (s1,S2,s3,...sn), it is necessary to convert the multiple subscripts to a single subscript for use in 
the single-dimensional AS/400 array. This single subscript can be computed using the following: 
$1+((s2-1)*d1)+(s3-1) *d1*d2)+...+((sn-1)*d*d2*d3*...*dm) 


where m = n-1 


The CAI instruction is used to form a single index value from two subscript values. To reduce N sub- 
script values into a single index value, N-1 uses of this instruction are necessary. 


Assume that S1, S2, and S3 are three subscript values and that D1 is the size of one dimension, D2 is 
the size of the second dimension, and the D1D2 is the product of D1 and D2. The following two uses of 
this instruction reduce the three subscripts to a single subscript. 


CAI INDEX, S1, S2, Dl Calculates sl+(s2-1)*d1l 
CAI INDEX, INDEX, S3, D1D2 Calculates sl+(s2-1)*d1+(s3-1)*d2*d1 


Exceptions 


Exception 1 2 3 4 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment 
03 Range 


x KK XK 
x KK XK 
x KK XK 
x K KK 


06 Optimized addressability invalid 
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Exception 


08 


We 


10 


1c 


20 


22 


24 


2E 


36 


Argument/parameter 


01 Parameter reference violation 


Computation 


0A size 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Compute Array Index (CAI) 


Operands 
1 2 3 4 Other 


X 
X 
X 
X X X X 
X X X X 
X X: X X 
X 
X X X X 
X X X X 
X 
X 
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Compute Math Function Using One Input Value (CMF1) 


Compute Math Function Using One Input Value (CMF1) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 
CMF1 Receiver Controls Source 

100B 

CMF1B Branch options Receiver Controls Source Branch targets 
1COB 

CMF1I Indicator Receiver Controls Source Indicator targets 
180B options 


Operand 1: Numeric variable scalar. 
Operand 2: Character(2) scalar (fixed tength). 
Operand 3: Numeric scalar. 


Operand 4-5: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The mathematical function, indicated by the controls operand, is performed on the source 
Operand value and the result is placed in the receiver operand. 


The calculation is always done in floating-point. 
The result of the operation is copied into the receiver operand. 


The controls operand must be a character scalar that specifies which mathematical function is to be 
performed. It must be at least 2 bytes in length and has the following format: 


« Controls operand Char(2) 


— Hex 0001 = Sine 

— Hex 0002 = Arc sine 

— Hex 0003 = Cosine 

— Hex 0004 = Arc cosine 

— Hex 0005 = Tangent 

— Hex 0006 = Arc tangent 

— Hex 0007 = Cotangent 

— Hex 0010 = Exponential function 

— Hex 0011 = Logarithm based e (natural logarithm) 
— Hex 0012 = Sine hyperbolic 

— Hex 0013 = Cosine hyperbolic 

— Hex 0014 = Tangent hyperbolic 

— Hex 0015 = Arc tangent hyperbolic 
— Hex 0020 = Square root 

— All other values are reserved 


The controls operand mathematical functions are as follows: 
« Hex 0001-Sine 
The sine of the numeric value of the source operand, whose value is considered to be in radians, 
is computed and placed in the receiver operand. 
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The result is in the range: 
-l1 < SIN(x) <1 
Hex 0002-Arc sine 


The arc sine of the numeric value of the source operand is computed and the result (in radians) is 
placed in the receiver operand. 


The result is in the range: 
-pi/2 < ASIN(x) <$ +pi/2 
Hex 0003-Cosine 


The cosine of the numeric value of the source operand, whose value is considered to be in 
radians, is computed and placed in the receiver operand. 


The result is in the range: 
-1 $ COS(x) $1 
Hex 0004-Arc cosine 


The arc cosine of the numeric value of the source operand is computed and the result (in radians) 
is placed in the receiver operand. 


The result is in the range: 
0 < ACOS(x) < pi 
Hex 0005-Tangent 


The tangent of the source operand, whose value is considered to be in radians, is computed and 
the result is placed in the receiver operand. 

The result is in the range: 

-infinity < TAN(x) < tinfinity 


Hex 0006-Arc tangent 


The arc tangent of the source operand is computed and the result (in radians) is placed in the 
receiver operand. 


The result is in the range: 
-pi/2 < ATAN(x) < pi/2 
Hex 0007-Cotangent 


The cotangent of the source operand, whose value is considered to be in radians, is computed and 
the result is placed in the receiver operand. 


The result is in the range: 
-infinity < COT(x) < +infinity 


Hex 0010-Exponential function 


The computation e power (source operand) is performed and the result is placed in the receiver 
operand. 


The result is in the range: 
0 < EXP(x) < +infinity 
Hex 0011-Logarithm based e (natural logarithm) 


The natural logarithm of the source operand is computed and the result is placed in the receiver 
operand. 


The result is in the range: 
-infinity < LN(x) < tinfinity 
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« Hex 0012-Sine hyperbolic 


The sine hyperbolic of the numeric value of the source operand is computed and the result (in 
radians) is placed in the receiver operand. 


The result is in the range: 
-infinity < SINH(x) < +infinity 


« Hex 0013-Cosine hyperbolic 


The cosine hyperbolic of the numeric value of the source operand is computed and the result (in 
radians) is placed in the receiver operand. 


The result is in the range: 
+1 < COSH(x) < t+infinity 
e Hex 0014-Tangent hyperbolic 


The tangent hyperbolic of the numeric value of the source operand is computed and the result (in 
radians) is placed in the receiver operand. 


The result is in the range: 
-1 < TANH(x) < +1 
e Hex 0015-Arc tangent hyperbolic 


The inverse of the tangent hyperbolic of the numeric value of the source operand is computed and 
the result (in radians) is placed in the receiver operand. 


The result is in the range: 
-infinity < ATANH(x) < +infinity 
e Hex 0020-Square root 


The square root of the numeric value of the source operand is computed and placed in the receiver 
operand. 


The result is in the range: 
0 < SQRT(x) < tinfinity 


The following chart shows some special cases for certain arguments (X) of the different mathematical 
functions. 
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X ri ea Maximum | Minimum 
— 7 ae a. ag 7 Value Value Other 
go fae) 


eee ee 
cosine aver [an [ao [1 [> [ann darn lam 
arceosne fp [wer [an [a [roi [nit [awn [wen | 
Tangent_|a_[wer__[an [an [+o _[o [ann [aso laa 
iecteaeas [ar [voit [ove [vo fa 
catrgen oa [AO [ao [rant [wt lan [aaa 
Sn en ce eed 


Sine A(e) + inf a 

hyperbolic 

Cosine A(e) +inf +inf 

hyperbolic 

Tangent A(e) +1 ~1 +0 

hyperbolic 

Arc tangent A(e) A(6,f) A(6,f) 
epee 


Figure 2-1. Special cases for arguments of CMF! mathematical functions. 


Capital letters in the chart indicate the exceptions, small letters indicate the returned results, and 
Arabic numerals indicate the limits of the arguments (X) as defined in the following lists: 


A = Floating-point invalid operand (hex 0CO9) exception (no result stored if unmasked; if masked, 
occurrence bit is set) 

B = Floating-point inexact result (nex OCOD) exception (result is stored whether or not exception is 
masked) 

C = Floating-point overflow (hex OCO6) exception (no result is stored if unmasked; if masked, occur- 
rence bit is set) 

D = Floating-point underflow (hex 0CO7) exception (no result is stored if unmasked; occurrence bit is 
always set) 


a= _ Result follows the rules that depend on round mode 
b = Result is +0 or a denormalized value 

c = Result is +infinity 

d= _ Result is -infinity 

e = Result is the masked form of the input NaN 

f= Result is the system default masked NaN 


g = Result is the input NaN j 
inf = Result is infinity 
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{= | pi* 27°50 | =Hex 432921FB54442018 

= Argument is in the range: -inf < x < -0 
= | pi* 2**26 | =Hex 41A4921FB54442D18 
4n(2"*1023) Hex 40862E42FEFA39EF 

=  41n(2"*-1021.4555) =Hex C086200000000000 


OA nm kK WD LD 
il 


= Argumentis inthe range: -1<x<-+1 


The following chart provides accuracy data for the mathematical functions that can be invoked by this 
instruction. 
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Accuracy Data 


Sample Selection Relative Error (e) Absolute Error (E) 


Function 
Name Range of x 
aed al 0<=x <= 314 a 2.11*10°*-15 


Arc tangent| Arc tangent| 1 | al -pi/2 | -pi/2 <x < pid x < | -pi/2 <x < pid ae | 33 * 10**-16 | 9.57 * 10**-17 


Arc tangent| 1 -3<=x<=3 ae: O06 * 10**-14 | 1.79 * 10**-15 
ga ae 


Cosine | (See Sine below) | | (See Sine below) | below) 


—- we: sine a 

hyperbolic below) 

Cotangent | 11 -10 <= x <= 100 |U |4.83 * 10°*-16| 1.48 * 10**-16 
.000001 <= x <= .001/U |4.36 * 10**-16| 1.49 * 10**-16 
000 <= x <= 400000@U [5.72 * 10**-16! 1.46 * 10**-16 


Exponential Es 100 <= x <= 300 }U |5.70 40°*-14| 1.13 * 10°14 ae ae 
EN o5<=x<=15 JU{ | sa. t0°-46 | 8.01 * 10°*-17 


fa | 100 <= x <= 700 FE 2.17 * 40°*-16| 7.37 * 10°*-17 


00001 <= x <= 2 NE Aid BY 1.56 * 107-16 
4000 < = x < = 4000001 <= 4000 < = x < = 4000001 < = 4000000 U | a 33° 1077-16 | 8.17 * 10°*-17 


hyperbolic 
Peetu ecmsiouer 
Tangent eee eae 4.59 * 10°*-16| 1.54 * 10**-16 i 


Tangent -100 <= x <= 300 |U [8.35 * 10**-16| 3.87 * 10**-17 /2.22 * 10**-16 {3.17 * 10**-17 
hyperbolic 


Figure 2-2 (Part 1 of 2). Accuracy data for CMF1 mathematical functions. 
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40o<=x<=100 [UJ = | sa. 2a t0%*-16 44.317 10-18 |. 


9 


Compute Math Function Using One Input Value (CMF1) 


Algorithm Notes: 


. f(x) x, and g(x) = ATAN(TAN(x)). 

f(x) e**x, and g(x) = e**(1n(e**x)). 

f(x) 1in(x), and g(x) = 1n(e**(1Nn(x))). 

f(x) x, and g(x) = in(e**x). 

. Sum of squares algorithm. f(x) = 1, and g(x) = SIN(x))**2 + (COS(x))**2. 
. Double angle algorithm. f(x) - SIN(2x), and g(x) = 2*(SIN(x)"COS(x)). 
. f(x) = e(**x, and g(x) = (SQR(e**x))**2. 

. f(x) = TAN(x), and g(x) = SIN(x) / COS(x). 

. f(x) = x, and g(x) = ACOS(COS(x)). 

. f(x) xX, and g(x) = ASIN(SIN(x)). 

. f(x) = COT(x), and g(x) = COS(x) / SIN(x). 

. f(x) = SINH(2x), and g(x) = 2*(SINH(x)*COSH(x)). 

. f(x) = TANH(x), and g(x) = SINH(x) / COSH(x). 

. f(x) = x, and g(x) = ATANH(TANKH(x)). 


Distribution Note: The sample input arguments were tangents of numbers, x, uniformly distributed 
between -pi/2 and +pi/2. 


1 

2. 
3. 
4. 
) 
6 
t 
8 


Figure 2-2 (Part 2 of 2). Accuracy data for CMF! mathematical functions. 


The vertical columns in the accuracy data chart have the following meanings: 


e Function Name: This column identifies the principal mathematical functions evaluated with entries 
arranged in alphabetical order by function name. 


« Sample Selection: This column identifies the selection of samples taken for a particular math func- 
tion through the following subcolumns: 


— A: identifies the algorithm used against the argument, x, to gather the accuracy samples. The 
numbers in this column refer to notes describing the functions, f(x) and g(x), which were calcu- 
lated to test for the anticipated relation where f(x) should equal g(x). An accuracy sample then, 
is an evaluation of the degree to which this relation held true. The algorithm used to sample 
the arctangent function, for example, defines g(x) to first calculate the tangent of x to provide 
an appropriate distribution of input arguments for the arctangent function. Since f(x) is defined 
simply as the value of x, the relation to be evaluated is then x=ARCTAN(TAN(x)). This type of 
algorithm, where a function and its inverse are used in tandem, is the usual type employed to 
provide the appropriate comparison values for the evaluation. 


— “Range of x”: gives the range of x used to obtain the accuracy samples. The test values for x 
are uniformly distributed over this range. It should be noted that x is not always the direct 
input argument to the function being tested; it is sometimes desirable to distribute the input 
arguments in a nonuniform fashion to provide a more complete test of the function (see column 
D below). For each function, accuracy data is given for one or more segments within the valid 
range of x. In each case, the numbers given are the most meaningful to the function and range 
under consideration. 


— D: identifies the distribution of arguments input to the particular function being sampled. The 
letter E indicates an exponential distribution. The letter U indicates a uniform distribution. A 
number refers to a note providing detailed information regarding the distribution. 


¢« Accuracy Data: The maximum relative error and standard deviation of the relative error are gener- 
ally useful and revealing statistics; however, they are useless for the range of a function where its 
value becomes zero. This is because the slightest error in the argument can cause an unpredict- 
able fluctuation in the magnitude of the answer. When a small argument error would have this 
effect, the maximum absolute error and standard deviation of the absolute error are given for the 
range. 
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— Relative Error (e): The maximum relative error and standard deviation (root mean square) of 
the relative error are defined: 


MAX(e) = MAX( ABS((f(x) - g(x) ) / f(x))) — 


where: MAX selects the largest of its arguments and ABS takes the absolute 
value of its argument. 


SD(e) = — SQR(_(1/N) SUMSQ((F(x) - g(x) ) / f(x))) 


where: SQR takes the square root of its argument and SUMSQ takes the summa- 
tion of the squares of its arguments over all of the test cases. 


— Absolute Error (E): The maximum absolute error produced during the testing and the standard 
deviation (root mean square) of the absolute error are: 


MAX(E) = MAX( ABS( f(x) - g(x) ) ) 
where: the operators are those defined above. 
SD(E) = SQR( (1/N) SUMSQ( f(x) - g(x) } ) 


where: the operators are those defined above. 
Limitations: The following are limits that apply to the functions performed by this instruction. 


The source and receiver operands must both be specified as floating-point with the same length (4 

bytes for short format or 8 bytes for long format). 

Resultant Conditions 
e Positive-The algebraic value of the receiver operand is positive. 
e Negative-The algebraic value of the receiver operand is negative. | 
e Zero-The algebraic value of the receiver operand is zero. a 


e Unordered-The value assigned to the floating-point result is NaN. 


Exceptions 


Exception 1 2 3 Other 
06 Addressing 
01 Spacing addressing violation X 
02 Boundary alignment violation X 
03 Range X 
06 Optimized addressability invalid X 


x KK XK 
x *— KK XK 


08 Argument/parameter 


01 Parameter reference violation X X X 


0c Computation 
06 Floating-point overflow X 
07 Floating-point underflow X 
09 Floating-point invalid operand X 


OD Floating-point inexact result X 


10 Damage encountered Jd 


04 System object damage state X 
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Exception 


1C 


20 


22 


24 


2C 


2E 


32 


36 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


02 Process storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


03 Scalar value invalid 


Space management 


01 space extension/truncation 


Compute Math Function Using One Input Value (CMF1) 


Operands 

1 2 3 Other 
X 
X 
X 
X 

X X X 

Xx X X 

X X X 
X 

X X X 

X X X 
X 
X 
X 

X X X 

X 

X 
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Compute Math Function Using Two Input Values (CMF2) 


Op Code Extender Operand 1 Operand 2 Operand 3 Operand 4 Operand [5-3] 
(Hex) 

CMF2 Receiver Controls Source 1 Source 2 

100C 

CMF2B Branch Receiver Controls Source 1 Source 2 Branch 

1COC options targets 

CMF2I _ Indicator Receiver Controls Source 1 Source 2 Indicator 
180C options targets 


Operand 1: Numeric variable scalar. 
Operand 2: Character(2) scalar (fixed length) 
Operand 3: Numeric scalar. 

Operand 4: Numeric scalar. 


Operand 5-8: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The mathematical function, indicated by the controls operand, is performed on the source 
operand values and the result is placed in the receiver operand. 


The calculation is always done in floating-point. 
The controls operand must be a character scalar that specifies which mathematical function is to be 
performed. It must be at least 2 bytes in length and have the following format: 
e Controls operand Char(2) 
— Hex 0001 = Power (x to the y) 
— All other values are reserved 
The computation x power y, where x is the first source operand and y is the second source operand, is 


performed and the result is placed in the receiver operand. 


The following chart shows some special cases for certain arguments of the power function (x**y). 
Within the chart, the capitalized letters X and Y refer to the absolute value of the arguments x and y; 
that is, X = |x| and Y = ly|. 
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+ 1/2 on y>0 y>0 +inf UnM- 
or y=2n | real we NaN 
ae 


y <0. y<0 
y= y= 2n real 
2n+1 


p+int | tint | int | | tint | | +int | | +int | tint | fb | Ate) 
+1 + | + 1 + a 
SQRT(x) + inf A(c) 
— a Se 


fb | Ale) | 


+] +1 +1 +1 +1 
O<x< 1 +inf SQRT(x) 
nY 7 —j SQRT(x) 


ee a fan for on Pe [ofa 
i za ere 


cm 
O>x>-1 | Afa) A(a) A(a) A(a) A(a) | Ala) A(c) 
—— — 


x=-1 [Alay | pet fala) | ) F+1 [ary | Faia) | Ala) | ) Faia) [b> | Alc) | 


+1 
A(a) my A(a) 


a Dae 
NaN 
Un- 
masked A(c} A(c) A(c) A(c) A(c) A(c) A(c) A(c) | A(e) | A(e) 
NaN 


Figure 2-3. Special cases of the power function (x**y) 


Capital letters in the chart indicate the exceptions and smail letters indicate the returned results as 
defined in the following list: 


A Floating-point invalid operand (hex 0CO9) exception 
E Divide by zero (hex OCOE) exception 

a Result is the system default masked NaN 

b 


Result is the same NaN 


Cc Result is the same NaN masked 
d Result is the larger NaN 
e Result is the larger NAN masked 


f Result is +infinity 
g Result is -infinity 


The following chart provides accuracy data for the mathematical function that can be invoked by this 
instruction. 
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Sample Selection Accuracy Data 


da a 
Name 

fe ft <a y on oan ome fae OE 
57 <=y <= 57 7.24 * 10°*-16 


Figure 2-4. Accuracy data for CMF2 mathematical functions. 


The vertical columns in the accuracy data chart have the following meanings: 
e Function Name: This column identifies the mathematical function. 


¢ Sample Selection: This column identifies the selection of samples taken for the power function. 
The algorithm used against the arguments, x and y, to gather the accuracy samples was a test for 
the anticipated relation where f(x) should equal g(x,y): 


where: 

f (x)= x 

g(x,y)= (x**y) **(1/y) 

An accuracy sample then, is an evaluation of the degree to which this relation held true. 


The range of argument values for x and y were selected such that x was held constant at a partic- 
ular value and y was uniformly varied throughout a range of values which avoided overflowing or 
underflowing the result field. The particular values selected are indicated in the subcolumns enti- 
tled x and y. 


e Accuracy Data: The maximum relative error and standard deviation (root mean square) of the rela- 
tive error are generally useful and revealing statistics. These statistics for the relative error, (e), 
are provided in the following subcolumns: 


MAX(e) = MAX( ABS ( f(x) - g(x) ) / fx) ) ) 


where: MAX selects the largest of its arguments and ABS takes the absolute value of 
its argument. 


SD(e) = SQR( (1/N) SUMSQ((f(x) - g(x) ) / f(x) 
where: SQR takes the square root of its argument and SUMSQ takes the summation 
of the squares of its arguments over all of the test cases. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


The source and receiver operands must both be specified as floating-point with the same length (4 
bytes for short format or 8 bytes for long format). 
Resultant Conditions 

¢ Positive-The algebraic value of the receiver operand is positive. 

e Negative-The algebraic value of the receiver operand is negative. 

« Zero-The algebraic value of the receiver operand is zero. 


¢« Unordered-The value assigned to the floating-point result is NaN. 
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Exceptions 


Exception 


06 


08 


OC 


1C 


20 


22 


24 


2C 


2E 


32 


Addressing 

01 space addressing violation 

02 boundary alignment violation 
03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 

06 floating-point overflow 

07 floating-point underflow 

09 floating-point invalid operand 
OC invalid floating-point conversion 
0D floating-point inexact result 


OE floating-point zero divide 


Damage encountered 


Compute Math Function Using Two Input Values (CMF2) 


Operands 

1 2 3 4 Other 
X X X X 

X X X X 

X X X X 

X X X X 


< 


04 System object damage state X 
44 partial system object damage X 
Machine-dependent exception 

03 machine storage limit exceeded X 
Machine support 

02 machine check X 
03 function check X 
Object access 

01 object not found X X Xx Xx 

02 object destroyed X X X X 

03 object suspended X X X X 

08 object compressed xX 
Pointer specification 

01 pointer does not exist X X X Xx 

02 pointer type invalid Xx X X X 
Program execution 

04 invalid branch target X 
Resource control limit 

01 user profile storage limit exceeded X 
02 process storage limit exceeded X 


Scalar specification 


01 scalar type invalid 
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Operands 
Exception 1 2 3 4 Other 
03 scalar value invalid - X 
36 Space management 
01 space extension/truncation X 
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Concatenate (CAT) 


Op Code (Hex) | Operand 1 Operand 2 Operand 3 
10F3 Receiver Source 4 Source 2 


Operand ?: Character variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character scalar. 


Description: The character string value of the second source operand is joined to the right end of the 
character string value of the first source operand. The resulting string value is placed (left-adjusted) in 
the receiver operand. 


The length of the operation is equal to the length of the receiver operand with the resulting string trun- 
cated or is logically padded on the right end accordingly. The pad value for this instruction is hex 40. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1, 2, and 3. The effect of specifying a null substring reference for one source 
operand is that the other source operand is used as the result of the concatenation. The effect of 
specifying a null substring reference for both source operands is that the bytes of the receiver are 
each set with a value of hex 40. The effect of specifying a null substring reference for the receiver is 
that a result is not set regardless of the value of the source operands. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 space addressing violation 
02 boundary alignment 


03 range 


x KK 
x KX K XK 
x KK XK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X 


10 Damage encountered 
04 system object damage state X X X X 
44 partial system object damage X X Xx xX 


1c Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X X 
02 object destroyed X X xX 
03 object suspended xX X xX 
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Exception 

08 object compressed 
24 Pointer specification 

01 pointer does not exist 


02 pointer type invalid 


2E Resource control limit 


01 user profile storage limit exceeded 


36 Space management 


01 space extension/truncation 


Concatenate (CAT) 


Operands 

1 2 3 Other 
X 

X X X 

X X X 
X 
X 
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Convert BSC to Character (CVTBC) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-6] 
CVTBC Receiver Controls Source 

10AF 

CVTBCB Branch options Receiver Controls Source Branch targets 
1CAF 

CVTBCI Indicator Receiver Controls Source Indicator targets 
18AF options 


Operand 1: Character variable scalar. 
Operand 2: Character(3) variable scalar (fixed-length). 
Operand 3: Character scalar. 


Operand 4-6: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
| CVTBC ( 

var receiver : aggregate; 
receiver_length : unsigned binary; 

var controls : aggregate; 

var source : aggregate; 
source_length : unsigned binary; 

var return_code : signed binary 


The return_code will be set as follows: 


Return_Code Meaning 

-1 Completed Record. 
8 Source Exhausted. 
1 Truncated Record. 


Description: This instruction converts a string value from the BSC (binary synchronous communi- 
cations) compressed format to a character string. The operation converts the source (operand 3) from 
the BSC compressed format to character under control of the controls (operand 2) and places the 
result into the receiver (operand 1). 


The source and receiver operands must both be character strings. 


The controls operand must be a character scalar that specifies additional information to be used to 
control the conversion operation. It must be at least 3 bytes in length and have the following format: 
« Controls operand Char(3) 


— Source offset Bin(2) 
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— Record separator Cnar(1) 


The source offset specifies the offset where bytes are to be accessed from the source operand. lf the 
source offset is equal to or greater than the length specified for the source Operand (it identifies a byte 
beyond the end of the source operand), a template value invalid (hex 3801) exception is signaled. As 
output from the instruction, the source offset is set to specify the offset that indicates how much of the 
source is processed when the instruction ends. 


The record separator, if specified with a value other than hex 01, contains the value used to separate 
converted records in the source operand. A value of hex 01 specifies that record separators do not 
occur in the converted records in the source. 


Only the first 3 bytes of the controls operand are used. Any excess bytes are ignored. 


The operation begins by accessing the bytes of the source operand located at the offset specified in 
the source offset. This is assumed to be the start of a record. The bytes of the record in the source 
operand are converted into the receiver record according to the following algorithm. 


The strings to be built in the receiver are contained in the source as blank compression entries and 
strings of consecutive nonblank characters. 


The format of the blank compression entries occurring in the source are as follows: 


e Blank compression entry Char(2) 
— Interchange group separator -Char(1) 
— Count of compressed blanks Char(1) 


The interchange group separator has a fixed value of hex 1D. 


The count of compressed blanks provides for describing up to 63 compressed blanks. The count of the 
number of blanks (up to 63) to be decompressed is formed by subtracting hex 40 from the value of the 
count field. The count field can vary from a value of hex 41 to hex 7F. If the count field contains a 
value outside of this range, a conversion (hex 0C01) exception is signaled. 


Strings of blanks described by blank compression entries in the source are repeated in the receiver 
the number of times specified by the blank compression count. 


Nonblank strings in the source are copied into the receiver intact with no alteration. 


If the receiver record is filled with converted data without encountering the end of the source operand, 
the instruction ends with a resultant condition of completed record. This can occur in two ways. Ifa 
record separator was not specified, the instruction ends when enough bytes have been converted from 
the source to fill the receiver. If a record separator was specified, the instruction ends when a source 
byte is encountered with that value prior to or just after filling the receiver record. The source offset 
value locates the byte following the last source record (including the record separator) for which con- 
version was completed. When the record separator value is encountered, any remaining bytes in the 
receiver are padded with blanks. 


™~ 


If the end of the source operand is encountered (whether or not in conjunction with a record separator 
or the filling of the receiver), the instruction ends with a resultant condition of source exhausted. The 
source offset value locates the byte following the last byte of the source operand. The remaining bytes 
in the receiver after the converted record are padded with blanks. 


If the converted form of a record cannot be completely contained in the receiver, the instruction ends 
with a resultant condition of truncated record. The offset value for the source locates the byte fol- 
lowing the last source byte for which conversion was performed, unless a blank compression entry 
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was being processed. In this case, the source offset is set to locate the byte after the blank com- 
pression entry. If the source does not contain record separators. this condition can only occur for the 
case in which a blank- compression entry was being converted when the receiver record became full. 


Any form of overlap between the operands on this instruction yields unpredictable results in the 
receiver operand. 


Resultant Conditions 


Exceptions 


Exception 


06 


08 


We 


10 


1C 


20 


22 


24 


Addressing 

01 space addressing violation 

02 boundary alignment violation 
03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 


01 conversion 


Damage encountered 
04 System object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Completed record-The receiver record has been completely filled with converted data from a 
source record. 


source exhausted-All of the bytes in the source operand have been converted into the receiver 
operand. 


Truncated record-The receiver record cannot contain all of the converted data from the source 
record. 


Operands 
1 2 3 Other 


X X X 
X X X 
X X X 
X X X 
X X X 
X 

X 

X 

X 

X 

X 
X X X 
X X X 
X X X 

X 
X X X 
X X X 
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Exception 


2C 


2E 


32 


36 


38 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Convert BSC to Character (CVTBC) 


Operands 
1 2 3 Other 
X 
X 
X X X 
X 
X 
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Convert Character to BSC (CVTCB) 


Op Code (Hex) ‘Extender Operand 1 Operand 2 Operand 3 Operand [4-5 | 
CVTCB Receiver Controls Source 

108F 

CVTCBB Branch options Receiver Controls Source Branch targets 
1C8F 

CVTCB Indicator Receiver Controls Source Indicator targets 
188F options 


Operand f: Character variable scalar. 
Operand 2: Character(3) variable scalar (fixed-length). 
Operand 3: Character scalar. 


Operand 4-3: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
| CVTCB { 

var receiver : aggregate; 
receiver_length : unsigned binary; 

var controls : aggregate; 

var source : aggregate; 
source_length : unsigned binary; 

var return_code : signed binary 


The return_code will be set as follows: 


Return_Code Meaning 
-1 Receiver Qverrun. 
3) Source Exhausted. 


Description: This instruction converts a string value from character to BSC (binary synchronous com- 
munications) compressed format. The operation converts the source (operand 3) from character to the 
BSC compressed format under control of the controls (operand 2) and places the result into the 
receiver (operand 1). 


The source and receiver operands must both be character strings. 


The controls operand must be a character scalar that specifies additional information to be used to 
control the conversion operation. It must be at least 3 bytes in length and have the following format: 


e Controls operand Char(3) 
— Receiver offset Bin(2) 
— Record separator Char(1) 
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The receiver offset specifies the offset where bytes are to be placed into the receiver Operand. Ifthe 
receiver offset is equal to or greater than the length specified for the receiver operand (it identifies a 
byte beyond the end of the receiver), a template value invalid (hex 3801) exception is signaled. As 
output from the instruction, the receiver offset is set to specify the offset that indicates how much of the 
receiver has been filled when the instruction ends. 


The record separator, if specified with a value other than hex 01, contains the value used to separate 
converted records in the receiver operand. A value of hex 01 specifies that record separators are not 
to be placed into the receiver to separate converted records. 


Only the first 3 bytes of the controls operand are used. Any excess bytes are ignored. 


The source operand is assumed to be one record. The bytes of the record in the source operand are 
converted into the receiver operand at the location specified in the receiver offset according to the fol- 
lowing algorithm. 


The bytes of the source record are interrogated to identify the strings of consecutive blank (hex 40) 
characters and the strings of consecutive nonbiank characters which occur in the source record. Only 
three or more blank characters are treated as a blank string for purposes of conversion into the 
receiver. 


As the blank and nonblank strings are encountered in the source, they are packaged into the receiver. 


Blank strings are reflected in the receiver as one or more blank compression entries. The format of 
the blank compression entries built into the receiver are as follows: 


~ 


e Blank compression entry Char(2) 
— Interchange group separator Char(1) 
— Count of compressed blanks Char(1) 


The interchange group separator has a fixed value of hex 1D. 


The count of compressed blanks provides for compressing up to 6&3 blanks. The value of the count field 
is formed by adding hex 40 to the actual number of blanks (up to 63) to be compressed. The count 
field can vary from a value of hex 43 to hex 7F. 


Nonblank strings are copied into the receiver intact with no alteration or additional! control information. 


When the end of the source record is encountered, the record separator value if specified is placed into 
the receiver and the instruction ends with a resultant condition of source exhausted. The receiver 
offset value locates the byte following the converted record in the receiver. The value of the remaining 
bytes in the receiver after the converted record is unpredictable. 


If the converted form of a record cannot be completely contained in the receiver (including the record 
separator if specified), the instruction ends with a resultant condition of receiver overrun. The receiver 
offset remains unchanged. The remaining bytes in the receiver, starting with the byte located by the 
receiver offset, are unpredictable. 


Any form of overlap between the operands on this instruction yields unpredictable results in the 
receiver operand. 


Resultant Conditions 


¢ Source exhausted-All of the bytes in the source operand have been converted into the receiver 
operand. 


e Receiver overrun-An overrun condition in the receiver operand was detected before all of the bytes 
in the source operand were processed. 


Chapter 2. Computation and Branching Instructions 2-53 


Exceptions 


Exception 


06 


08 


10 


1C 


20 


22 


24 


2C 


2E 


32 


36 


38 


Addressing 

01 space addressing violation 
02 boundary alignment violation 
03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 System object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Convert Character to BSC (CVTCB) 


Operands 
1 2 3 Other 
X X X 
X X X 
X X X 
X X X 
X X X 
X 
X 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X X X 
X 
X 
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Convert Character to Hex (CVTCH) 


Op Code (Hex) Operand 1 Operand 2 
1082 Receiver Source 


Operand 1: Character variable scalar. 
Operand 2: Character variable scalar. 


Description: Each character (8-bit value) of the string value in the source operand is converted to a 
hex digit (4-bit value) and placed in the receiver operand. The source operand characters must relate 
to valid hex digits or a conversion (hex 0C01) exception is signaled. 


Characters Hex Digits 
Hex FQ-hex FY Hex O0-hex 9 
Hex C1-hex C& Hex A-hex F 


The operation begins with the two operands left-adjusted and proceeds left to right until all the hex 
digits of the receiver operand have been filled. If the source operand is too small, it is logically 
padded on the right with zero characters (hex FQ). If the source operand is too large, a /Jength con- 
formance (hex 0C0O8) or an invalid operand length (hex 2A0A) exception is signaled. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that 
the bytes of the receiver are each set with a value of hex 00. The effect of specifying a null substring 
reference for the receiver is that no result is set. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
0c Computation 

01 conversion X 

08 length conformance X 
10 Damage encountered 

04 system object damage X X X 

44 partial system object damage X X X 
1c Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check X 
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Exception 


22 


24 


2E 


36 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Convert Character to Hex (CVTCH) 


Operands 
1 2 Other 
X 
X Xx 
X X 
Xx X 
X 
x xX 
X X 
X 
X 


Chapter 2. Computation and Branching Instructions 2-56 


Convert Character to MRJE (CVTCM) 


Convert Character to MRJE (CVTCM) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 


CVTCM Receiver Controls Source 

108B 

CVTCMB Branch options Receiver Controis Source Branch targets 
1C8B 

CVTCMI Indicator Receiver Controls Source Indicator targets 
188B options 


Operand 7: Character variable scalar. 
Operand 2: Character(13) variable scalar (fixed-length). 
Operand 3: Character scalar. 


Operand 4-5: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
CVTCM ( 
var receiver : aggregate; 
receiver_length : unsigned binary; 
var controls : aggregate; 
var source : aggregate; 
source_length : unsigned binary; 
var return_code : signed binary 
) 
The return_code will be set as follows: 
Return_Code Meaning 
-1 Receiver Overrun. 
6 Source Exhausted. 


Description: This instruction converts a string of characters to MRJE (MULTI-LEAVING remote job 
entry) compressed format. The operation converts the source (operand 3) from character to the MRJE 
compressed format under control of the controls (operand 2) and places the results in the receiver 
(operand 1). 


The source and receiver operands must both be character strings. The source operand cannot be 
specified as either a signed or unsigned immediate value. 


The source operand can be described through the controls operand as being composed of one or more 
fixed length data fields, which may be separated by fixed length gaps of characters to be ignored 
during the conversion operation. Additionally, the controls operand specifies the amount of data to be 
processed from the source to produce a converted record in the receiver. This may be a different 
value than the length of the data fields in the source. The following diagram shows this structure for 
the source operand. 
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Actual Source Opsrand Bytes 
nt Cata field =| gap data fleld gap data flald gap | 
Data Processed as Source Records 


AACO10-0 


The controls operand must be a character scalar that specifies additional information to be used to 
control the conversion operation. It must be at least 13 bytes in length and have the following format: 


« Controls operand Char(13) 
— Receiver offset Bin(2) 
— Source offset Bin(2) 
— Algorithm modifier Char(1) 
— Source record length Char(1) 
— Data field length Bin(2) 
— Gap offset Bin(2) 
— Gap length “Bin(2) 
— Record control block (RCB) value Char(1) 
_ As input to the instruction, the source offset and iver offset fields specify the offsets where bytes of the 


source and receiver operands are to be processed. If an offset is equal to or greater than the length 
specified for the operand it corresponds to (i.e. it identifies a byte beyond the end of the operand), a 
template value invalid (hex 3801) exception is signaled. As output from the instruction, the source 
offset and receiver offset fields specify offsets that indicate how much of the operation is complete 
when the instruction ends. 


The algorithm modifier has the following valid values: 
¢ Hex 00 = Perform full compression. 
« Hex 01 = Perform only truncation of trailing blanks. 


The source record length value specifies the amount of data from the source to be processed. Ifa 
source record length of 0 is specified, a template value invalid (hex 3801) exception is signaled. 


The data field length value specifies the length of the data fields in the source. Data fields occurring in 
the source may be separated by gaps of characters, which are to be ignored during the conversion 
operation. Specification of a data field length of 0 indicates that the source operand is one data field. 
In this case, the gap /Jength and gap offset values have no meaning and are ignored. 


The gap offset value specifies the offset to the next gap in the source. This value is both input to and 
output from the instruction. This is relative to the current byte to be processed in the source as 
located by the source offset field. No validation is done for this offset. It is assumed to be valid rela- 
tive to the source operand. The gap offset value is ignored if the data field length is specified with a 
value of 0. 


The gap length value specifies the amount of data occurring between data fields in the source operand 
which is to be ignored during the conversion operation. The gap /ength value is ignored if the data 
field length is specified with a value of 0. 


Chapter 2. Computation and Branching Instructions 2-98 


Convert Character to MRJE (CVTCM) 


The record control block (RCB) value field specifies the RCB value that is to precede the converted 
form of each record in the receiver. It can have any value. 


Only the first 13 bytes of the controls operand are used. Any excess bytes are ignored. 


The operation begins by accessing the bytes of the source operand at the location specified by the 
source offset. This is assumed to be the start of a source record. Only the bytes of the data fields in 
the source are accessed for conversion purposes. Gaps between data fields are ignored, causing the 
access of data field bytes to occur as if the data fields were contiguous with one another. Bytes 
accessed from the source for the source record length are considered a source record for the conver- 
sion operation. They are converted into the receiver operand at the location specified by the receiver 
offset according to the following algorithm. 


The RCB value is placed into the first byte of the receiver record. 


An SRCB (sub record control byte) value of hex 80 is placed into the second byte of the receiver 
record. 


If the algorithm modifier specifies full compression (a value of hex 00) then: 


The bytes of the source record are interrogated to locate the blank character strings (2 or more con- 
secutive blanks), identical character strings (3 or more consecutive identical characters), and noniden- 
tical character strings occurring in the source. A blank character string occurring at the end of the 
record is treated as a special case (see following information on trailing blanks). 


If the algorithm modifier specifies blank truncation (a value of hex 01) then: 


The bytes of the source record are interrogated to determine if a blank character string exists at the 
end of the source record. If one exists, it is treated as a string of trailing blanks. All characters prior 
to it in the record are treated as one string of nonidentical characters. 


The strings encountered (blank, identical, or nonidentical) are reflected in the receiver by building one 
or more SCBs (string control bytes) in the receiver to describe them. 


The format of the SCBs built into the receiver is: 


=e wee 


The bit meanings are: 


Bit Value Meaning 
o 0 End of record; the EOR SCB is hex 00. 
1 All other SCBs. 
kK 0 The string is compressed. 
1 The string is not compressed. 
| Fork = 0: 
0 Blanks (hex 40s) have been deleted. 
1 Nonblank characters have been deleted. The next character in the data stream is the 
specimen character. 
Fork = 1: 
This bit is part of the length field for length of uncompressed data. 
jy Number of characters that have been deleted if k = 0. The value can be 2-31. 
iii Number of characters to the next SCB (no compression) if k = 1. The value can be 


1-63. The uncompressed (nonidentical bytes) follow the SCB in the data stream. 
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When the end of a source record is encountered, an EOR (end of record) SCB (hex 00) is built into the 

receiver. Trailing blanks in a record including a record of all blanks are represented in the receiver by 
an EOR character. However, a record of all blanks is reflected in the compressed result by an RCB, an 
SRCB, a compression entry describing an ‘unlike string’ of one blank character, and an EOR character. 


Additionally, the receiver offset, the source offset, and the gap offset are updated in the controls 
operand. 


If the end of the source operand is not encountered, the operation then continues by reapplying the 
above algorithm to the next record in the source operand. 


lf the end of the source operand is encountered (whether or not in conjunction with a record boundary), 
the instruction ends with a resultant condition of source exhausted. The source offset locates the byte 
following the last source record for which conversion was completed. The gap offset value indicates 
the offset to the next gap relative to the source offset value set for this condition. The gap offset value 
has no meaning and is not set when the data field length is 0. The receiver offset locates the byte 
following the last fully converted record in the receiver. The value of the remaining bytes in the 
receiver after the last converted record is unpredictable. 


If the converted form of a record cannot be completely contained in the receiver, the instruction ends 
with a resultant condition of receiver overrun. The source offset locates the byte following the last 
source record for which conversion was completed. The gap offset value indicates the offset to the 
next gap relative to the source offset value set for this condition. The gap offset value has no meaning 
and is not set when the data field length is 0. The receiver offset locates the byte following the last 
fully converted record in the receiver. The value of the remaining bytes in the receiver after the last 
converted record is unpredictable. 


Any form of overlap between the operands of this instruction yields unpredictable results in the 
receiver operand. 


Resultant Conditions 


« Source exhausted-All complete records in the source operand have been converted into the 
receiver operand. 


¢ Receiver overrun-An overrun condition in the receiver operand was detected prior to processing all 
of the bytes in the source operand. 


If source exhausted and receiver overrun occur at the same time, the source exhausted condition is 
recognized first. When source exhausted is the resultant condition, the receiver may also be full. In 
this case, the receiver offset may contain a value equal to the length specified for the receiver, and this 
condition will cause an exception on the next invocation of the instruction. The processing performed 
for the source exhausted condition provides for this case when the instruction is invoked multiple times 
with the same controls operand template. When the receiver overrun condition is the resultant condi- 
tion, the source always contains data that can be converted. 


Exceptions 


Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment violation 


03 range 


x KK KK 
x KX XK KK 
x KX K KK 


06 optimized addressability invalid 
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Exception 


08 


10 


20 


22 


24 


2C 


2E 


32 


36 


38 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 System object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Convert Character to MRJE (CVTCM) 


Operands 
1 2 3 Other 
X X X 
X 
X 
X 
X 
Xx 
X X X 
Xx X X 
X X Xx 
X 
X X xX 
X X X 
X 
X 
X X X 
X 
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Convert Character to Numeric (CVTCN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
1083 Receiver Source Attributes 


Operand 1: Numeric variable scalar or data-pointer-defined numeric scalar. 
Operand 2: Character scalar or data-pointer-defined character scalar. 
Operand 3: Character(7) scalar or data-pointer-defined character scalar. 


Description: The character scalar specified by operand 2 is treated as though it were a numeric 
scalar with the attributes specified by operand 3. The character string source operand is converted to 
the numeric forms of the receiver operand and moved to the receiver operand. The value of operand 
2, when viewed in this manner, is converted to the type, length, and precision of the numeric receiver, 
operand 1, following the rules for the Copy Numeric Value instruction. 


The length of operand 2 must be large enough to contain the numeric value described by operand 3. If 
it is not large enough, a scalar value invalid (hex 3203) exception is signaled. lf it is larger than 
needed, its leftmost bytes are used as the value, and the rightmost bytes are ignored. 


Normal rules of arithmetic conversion apply except for the following. If operand 2 is interpreted as a 
zoned decimal value, a value of hex 40 in the rightmost byte referenced in the conversion is treated as 
a positive sign and a Zero digit. 


If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 


The format of the attribute operand specified by operand 3 is as follows: 
e Scalar attributes Char(7) 


— Scalar type Char(1) 


Hex 00 = Signed binary 
Hex 01 = Floating-point 
Hex 02 = Zoned decimal 
Hex 03 = Packed decimal 
Hex OA = Unsigned binary 


— Scalar length Bin(2) 
If binary: 
- Length (L) (where L = 2 or 4) Bits 0-15 


If floating-point: 
- Length (L) (where L 


If zoned decimal or packed decimal: 


4 or 8) Bits 0-15 


- Fractional digits (F) Bits 0-7 
- Total digits (T) Bits 8-15 
(where 1<7<31 andO<F<7) 
— Reserved (binary 0) Bin(4) 
Exceptions 
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Exception 


06 


08 


0c 


10 


20 


22 


24 


2E 


32 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

04 external data object not found 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 

02 decimal data 

06 floating-point overflow 

07 floating-point underflow 

09 floating-point invalid operand 
0A size 

OC floating-point conversion 


0D floating-point inexact result 


Damage encountered ~ 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 
02 scalar attribute invalid 


03 scalar value invalid 


Convert Character to Numeric (CVTCN) 


Operands 
1 2 3 Other 
X X. X 
X X X 
X X X 
X X X 
X X X 
X X X 
X X 
X 
X 
X 
X 
X 
X 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X X 
X 
X 
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Operands 
Exception 1 2 3 Other 
¥ 36 Space management 
he 01 space extension/truncation X 
‘Sr 
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Convert Character to SNA (CVTCS) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5 | 
CVTCS Receiver Controls Source 

10CB 
a 
CVTCSB Branch options Receiver Controls Source Branch targets 
1CCB 
a a es 
CVTCSI Indicator Receiver Controls Source Indicator targets 
18CB options 


Operand 1: Character variable scalar. 
Operand 2: Character(15) variable scalar (fixed length). 
Operand 3: Character scalar. 


Operand 4-5: 


e¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
CVTCS ( 

var receiver : aggregate; 
receiver_length : unsigned binary; 

var controls : aggregate; 

var source : aggregate; 
source _length =: unsigned binary; 

var return_code : signed binary 


The return_code will be set as follows: 


Return_Code Meaning 
-1 Receiver Qverrun. 
8 Source Exhausted. 


Description: This instruction converts the source (operand 3) from character to SNA (systems network 
architecture) format under control of the controls (operand 2) and places the result into the receiver 
(operand 1). 


The source and receiver operands must both be character strings. The source operand may not be 
specified as an immediate operand. 


The source operand can be described by the controls operand as being one or more fixed-length data 
fields that may be separated by fixed-length gaps of characters to be ignored during the conversion 
operation. Additionally, the controls operand specifies the amount of data to be processed from the 
source to produce a converted record in the receiver. This may be a different value than the length of 
the data fields in the source. The following diagram shows this structure for the source operand. 
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Actual Source Operand Bytes 


Data Processad as Source Records 


AACO10-0 


The controls operand must be a character scalar that specifies additional information to be used to 
control the conversion operation. The operand must be at least 15 bytes in length and has the fol- 
lowing format: 


e Controls operand Char(15) 
— Receiver offset Bin(2) 
— Source offset Bin(2) 
— Algorithm modifier Char(1) 
— Source record length Char(1) 
— Data field length Bin(2) 
— Gap offset | Bin(2) 
— Gap length Bin(2) 
— Record separator character Char(1) 
— Prime compression character Char(1) 
— Unconverted source record bytes Char(1) 


As input to the instruction, the source offset and receiver offset fields specify the offsets where the 
bytes of the source and receiver operands are to be processed. If an offset is equal to or greater than 
the length specified for the operand, the offset identifies a byte beyond the end of the operand and a 
template value invalid (hex 3801) exception is signaled. When the source offset and the receiver offset 
field are output from the instruction, they specify offsets that indicate how much of the operation is 
complete when the instruction ends. 


The algorithm modifier specifies the optional functions to be performed. Any combination of functions 
can be specified as indicated by the bit meanings in the following chart. At least one of the functions 
must be specified. If all of the algorithm modifier bits are zero, a template value invalid (hex 3801) 
exception is signaled. The algorithm modifier bit meanings are: 


Bits Meaning 
0 0 = Do not perform compression. 
1 = Perform compression. 
1-2 00 = Do not use record separators and no blank truncation. Do not perform data transparency 
conversion. 


01 = Reserved. 

10 = Use record separators and perform blank truncation. Do not perform data transparency con- 
version. 

11 = Use record separators and perform blank truncation. Perform data transparency conversion. 


3 0 = Do not perform record spanning. 
1 = Perform record spanning. (allowed only when bit 1 = 1) 
4-7 (Reserved) 


Chapter 2. Computation and Branching Instructions 2-66 


Convert Character to SNA (CVTCS) 


The source record length value specifies the amount of data from the source to be processed to 
produce a converted record in the receiver. Specification of a source record Jength of zero results in a 
template value invalid (hex 3801) exception. 


The data field length value specifies the length of the data fields in the source. Data fields occurring in 
the source may be separated by gaps of characters that are to be ignored during the conversion oper- 
ation. Specification of a data field length of zero indicates that the source operand is one data field. In 
this case, the gap length and gap offset values have no meaning and are ignored. 


The gap offset value specifies the offset to the next gap in the source. This value is both input to and 
output from the instruction. This is relative to the current byte to be processed in the source as 
located by the source offset value. No validation is done for this offset. It is assumed to be valid 
relative to the source operand. The gap offset value is ignored if the data field length is specified with 
a value of zero. 


The gap length value specifies the amount of data that is to be ignored between data fields in the 
source operand during the conversion operation. The gap /ength value is ignored if the data field 
length is zero. 


The record separator character value specifies the character that precedes the converted form of each 
record in the receiver. It also serves as a delimiter when the previous record is truncating trailing 
blanks. The Convert SNA to Character instruction recognizes any value that is less than hex 40. The 
record separator value is ignored if record separators are not used as specified in the a/gorithm modi- 
fier. 


The prime compression character value specifies the character to be used as the prime compression 
character when performing compression of the source data to SNA format. It may have any value. 
The prime compression character value is ignored if the perform compression function is not specified 


in the algorithm modifier. 


The unconverted source record bytes value specifies the number of bytes remaining in the current 
source record that are yet to be converted. 


When the record spanning function is specified in the a/gorithm modifier, the unconverted source 
record bytes field is both input to and output from the instruction. On input, a value of hex 00 means it 
is the start of a new record and the initial conversion step is yet to be performed. That is, a record 
separator character has not yet been placed in the receiver. On input, a nonzero value less than or 
equal to the source record length specifies the number of bytes remaining in the current source record 
that are yet to be converted into the receiver. This value is assumed to be the valid count of uncon- 
verted source record bytes relative to the current byte to be processed in the source as located by the 
source offset value. As such, it is used to determine the location of the next record boundary in the 
source Operand. This value must be less than or equal to the source record /ength value; otherwise, a 
template value invalid (hex 3801) exception is signaled. On output this field is set with a value as 
defined above that describes the number of bytes of the current source record that have not yet been 


converted. 


When the record spanning function is not specified in the algorithm modifier, the unconverted source 
record bytes value is ignored. : 


Only the first 15 bytes of the controls operand are used. Any excess bytes are ignored. 


The description of the conversion process is presented as a series of separately performed steps that 

may be selected in allowable combinations to accomplish the conversion function. It is presented this 

way to allow for describing these functions separately. However, in the actual execution of the instruc- 
tion, these functions may be performed in conjunction with one another or separately depending upon 

which technique is determined to provide the best implementation. 
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The operation is performed either on a record-by-record basis (record processing) or on a nonrecord 
basis (string processing). This is determined by the functions selected in the algorithm modifier. Spec- 
ifying the use record separators and perform blank truncation function indicates record processing is to 
be performed. lf this is not specified, in which case compression must be specified, it indicates that 


string processing is to be performed. 


The operation begins by accessing the bytes of the source operand at the location specified by the 
source offset. 


When record processing is specified, the source offset may \ocate the start of a full or partial record. 


When the record spanning function has not been specified in the a/gorithm modifier, the source offset is 
assumed to locate the start of a record. 


When the record spanning function has been specified in the algorithm modifier, the source offset is 
assumed to locate a point at which processing of a possible partially converted record is to be 
resumed. In this case, the unconverted source record bytes value contains the length of the remaining 
portion of the source record to be converted. The conversion process in this case is started by com- 
pleting the conversion of the current source record before processing the next full source record. 


When string processing is specified, the source offset locates the start of the source string to be con- 
verted. 


Only the bytes of the data fields in the source are accessed for conversion purposes. Gaps between 
data fields are ignored causing the access of data field bytes to occur as if the data fields were contig- 
uous. A string of bytes accessed from the source for a length equal to the source record length is 
considered to be a record for the conversion operation. 


When during the conversion process, the end of the source operation is encountered, the instruction 
ends with a resultant condition of source exhausted. 


When record processing is specified in the algorithm modifier, this check is performed at the start of 
conversion for each record. If the source operand does not contain a full record, the source exhausted 
condition is recognized. The instruction is terminated with status in the controls operand describing 
the last completely converted record. For source exhausted, partial conversion of a source record is 
not performed. 


When string processing is specified in the algorithm modifier, then compression must be specified and 
the compression function described below defines the detection of source exhausted. 


If the converted form of the source cannot be completely contained in the receiver, the instruction ends 
with a resultant condition of receiver overrun. See the description of this condition in the conversion 
process described below to determine the status of the controls operand values and the converted 
bytes in the receiver for each case. 


When string processing is specified, the bytes accessed from the source are converted on a string 
basis into the receiver operand at the location specified by the receiver offset. In this case, the com- 
pression function must be specified and the conversion process proceeds with the compression func- 
tion defined below. 


When record processing is specified, the bytes accessed from the source are converted one record at 
a time into the receiver operand at the location specified by the receiver offset performing the functions 
specified in the algorithm modifier in the sequence defined by the following algorithm. 
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The first function performed is trailing blank truncation.: A truncated record is built by logically 
appending the record data to the record separator value specified in the controls operand and 
removing all blank characters after the last nonbiank character in the record. If a record has no 
trailing blanks, then no actual truncation takes place. A null record, a record consisting entirely of 
blanks, will be converted as just the record separator character with no other data following it. The 
truncated record then consists of the record separator character followed by the truncated record data. 
the full record data, or no data from the record. 


lf either the data transparency conversion or the compression function is specified in the algorithm 
modifier, the conversion process continues for this record with the next specified function. 


If not, the conversion process for this record is completed by placing the truncated record into the 
receiver. If the truncated record cannot be completely contained in the receiver, the instruction ends 
with a resultant condition of receiver overrun. When the record spanning function is specified in the 
algorithm modifier, as much of the truncated record as will fit is placed into the receiver and the con- 
trols operand is updated to describe how much of the source record was successfully converted into 
the receiver. When the record spanning function is not specified in the algorithm modifier, the controls 
operand is updated to describe only the last fully converted record in the receiver and the value of the 
remaining bytes in the receiver is unpredictable. 


The second function performed is data transparency conversion.: Data transparency conversion is 
performed if the function is specified in the algorithm modifier. This provides for making the data in a 
record transparent to the Convert SNA to Character instruction in the area of its scanning for record 
separator values. Transparent data is built by preceding the data with 2 bytes of transparency control 
information. The first byte has a fixed value of hex 35 and is referred to as the TRN (transparency) 
control character. The second byte is a 1-byte hexadecimal count, a value ranging from 1 to 255 
decimal, of the number of bytes of data that follow and is referred to as the TRN count. This contains 
the length of the data and does not include the TRN control information length. 


Transparency conversion can be specified only in conjunction with record processing and, as such, is 
performed on the truncated form of the source record. The transparent record is built by preceding the 
data that follows the record separator in the truncated record with the TRN control information. The 
TRN count in this case contains the length of just the truncated data for the record and does not 
include the record separator character. For the special case of a null record, no TRN control informa- 
tion is placed after the record separator character because there is no record data to be made trans- 
parent. 


lf the compression function is specified in the algorithm modifier, the conversion process continues for 
this record with the compression function. 


If not, the conversion process for this record is completed by placing the transparent record into the 
receiver. If the transparent record cannot be completely contained in the receiver, the instruction ends 
with a resultant condition of receiver overrun. 


When the record spanning function is specified in the algorithm modifier, as much of the transparent 
record as will fit is placed into the receiver and the controls operand is updated to describe how much 
of the source record was successfully converted into the receiver. The TRN count is also adjusted to 
describe the length of the data successfully converted into the receiver; thus, the transparent data for 
the record is not spanned out of the receiver. The remaining bytes of the transparent record, if any, 
will be processed as a partial source record on the next invocation of the instruction and will be pre- 
ceded by the appropriate TRN control information. For the special case where only 1 to 3 bytes are 
available at the end of the receiver, (not enough room for the record separator, the transparency 
control, and a byte of data) then just the record separator is placed in the receiver for the record being 
converted. This can cause up to 2 bytes of unused space at the end of the receiver. The value of 
these unused bytes is unpredictable. 
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When the record spanning function is not specified in the algorithm modifier, the controls operand is 
updated to describe only the last fully converted record in the receiver and the value of the remaining 
bytes in the receiver is unpredictable. 


The third function performed is compression.: Compression is performed if the function is specified in 
the a/gorithm modifier. This provides for reducing the size of strings of duplicate characters in the 
source data. The source data to be compressed may have assumed a partially converted form at this 
point as a result of processing for functions specified in the a/gorithm modifier. Compressed data is 
built by concatenating one or more compression strings together to describe the bytes that make up 
the converted form of the source data prior to the compression step. The bytes of the converted 
source data are interrogated to locate the prime compression character strings (two or more consec- 
utive prime compression characters), duplicate character strings (three or more duplicate nonprime 
characters) and nonduplicate character strings occurring in the source. 


The character strings encountered (prime, duplicate and nonduplicate) are reflected in the compressed 
data by building one or more compression strings to describe them. Compression strings are com- 
prised of an SCB (string control byte) possibly followed by one or more bytes of data related to the 
character string to be described. 


The format of an SCB and the description of the data that may follow it are: 
« SCB Char(1) 
— Control Bits 0-1 


00 = n nonduplicate characters are between this SCB and the next one; where n is the value 
of the count field (1-63). | 

01 = Reserved 

10 = This SCB represents n deleted prime compression characters; where n is the value of the 
count field (2-63). The next byte is the next SCB. 

11 = This SCB represents n deleted duplicate characters; where n is the value of the count 
field (3-63). The next byte contains a specimen of the deleted characters. The byte fol- 
lowing the specimen character contains the next SCB. 


— Count Bits 2-7 


This contains the number of characters that have been deleted for a prime or duplicate string, 
or the number of characters to the next SCB for a nonduplicate string. A count value of zero 
cannot be produced. 


When record processing is specified, the compression is performed as follows. 


The compression function is performed on just the converted form of the current source record 
including the record separator character. The converted form of the source record prior to the com- 
pression step may be a truncated record or a transparent record as described above, depending upon 
the functions selected in the algorithm modifier. The record separator and TRN control information is 
always converted as a nonduplicate compression entry to provide for length adjustment of the TRN 
count, if necessary. 


The conversion process for this record is completed by placing the compressed record into the 
receiver. If the compressed record cannot be completely contained in the receiver, the instruction 
ends with a resultant condition of receiver overrun. 


When the record spanning function is specified in the algorithm modifier, as much of the compressed 
record as will fit is placed into the receiver and the controls operand is updated to describe how much 
of the source record was successfully converted into the receiver. The last compression entry placed 
into the receiver may be adjusted if necessary to a length that provides for filling out the receiver. 
This length adjustment applies only to compression entries for nonduplicate strings. Compression 
entries for duplicate strings are placed in the receiver only if they fit with no adjustment. For the 
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Special case where data transparency conversion is specified, the transparent data being described is 
not spanned out of the receiver. This is provided for by performing length adjustment on the TAN 
count of a transparent record, which may be included in the compressed data so that it describes only 
the source data that was successfully converted into the receiver. For the special case where only 2 to 
3 bytes are available at the end of the receiver, not enough room for the compression entry for a non- 
duplicate string containing the record separator and the TRN control, and up to a 2-byte compression 
entry for some of the transparent data, the nonduplicate compression entry is adjusted to describe only 
the record separator. By doing this, no more than 3 bytes of unused space will remain in the receiver. 
The value of these unused bytes is unpredictable. Unconverted source record bytes, if any, will be 
processed as a partial source record on the next invocation of the instruction and will be preceded by 
the appropriate TRN control information when performing transparency conversion. 


When the record spanning function is not specified in the algorithm modifier, the controls operand is 
updated to describe only the last fully converted record in the receiver. The value of the remaining 
bytes in the receiver is unpredictable. 


When string processing is specified, the compression is performed as follows. 


The compression function is performed on the data for the entire source operand on a compression 
string basis. In this case, the fields in the controls operand related to record processing are ignored. 


The conversion process for the source operand is completed by placing the compressed data into the 
receiver. 


When the compressed data cannot be completely contained in the receiver, ‘the instruction ends with a 
resultant condition of receiver overrun. As much of the compressed data as will fit is placed into the 
receiver and the controls operand is updated to describe how much of the source data was success- 
fully converted into the receiver. The last compression entry placed into the receiver may be adjusted 
if necessary to a length that provides for filling out the receiver. This length adjustment applies only to 
compression entries for nonduplicate strings. Compression entries for duplicate strings are placed in 
the receiver only if they fit with no adjustment. By doing this, no more than 1 byte of unused space will 
remain in the receiver. 


When the compressed data can be completely contained in the receiver, the instruction ends with a 
resultant condition of source exhausted. The compressed data is placed into the receiver and the con- 
trols operand is updated to indicate that all of the source data was successfully converted into the 
receiver. 


At this point, either conversion of a source record has been compieted or conversion has been inter- 
rupted due to detection of the source exhausted or receiver overrun conditions. For record processing, 
if neither of the above conditions has been detected either during conversion of or at completion of 
conversion for the current record, the conversion process continues on the next source record with the 
blank truncation step described above. 


At completion of the instruction, the receiver offset locates the byte following the last converted byte in 
the receiver. The value of the remaining bytes in the receiver after the last converted byte are unpre- 
dictable. The source offset locates the byte following the last source byte for which conversion was 
completed. When the record spanning function is specified in the algorithm modifier, the unconverted 
source record bytes field specifies the length of the remaining source record bytes yet to be converted. 
When the record spanning function is not specified in the algorithm modifier, the unconverted source 
record bytes field has no meaning and is not set. The gap offset value indicates the offset to the next 
gap relative to the source offset value set for this condition. The gap offset value has no meaning and 
is not set when the data field length is zero. 
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Limitations: The following are limits that apply to the functions performed by this instruction. 


Any form of overlap between the operands on this instruction yields unpredictable results in the 
receiver operand. 


Substring operand references that allow for a null substring reference (a length value of zero) may not 
be specified for this instruction. 


Resultant Conditions 


e Source exhausted - All bytes in the source operand have been converted into the receiver 
operand. 


* Receiver overrun - An overrun condition in the receiver operand was detected before all of the 
bytes in the source operand were processed. 


Programming Notes: 


If the source operand does not end on a record boundary, in which case the last record is 
spanned out of the source, this instruction performs conversion only up to the start of that 
partial record. In this case, the user of the instruction must move this partial record to combine 
it with the rest of the record in the source operand to provide for its being processed correctly 
upon the next invocation of the instruction. If full records are provided, the instruction performs 
its conversions out to the end of the source operand and no special processing is required. 


For the special case of a tie between the source exhausted and receiver overrun conditions, the 
source exhausted condition is recognized first. That is, when source exhausted is the resultant 
condition, the receiver may also be full. In this case, the receive offset may contain a value 
equal to the length specified for the receiver, which would cause an exception to be detected on 
the next invocation of the instruction. The processing performed for the source exhausted con- 
dition should provide for this case if the instruction is to be invoked multiple times with the 
same controls operand template. When the receiver overrun condition is the resultant condition, 
the source will always contain data that can be converted. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment violation 
03 Range 
06 Optimized addressability invalid 


x KK OK 
x «K K XK 
x KK 


08 Argument/parameter 


01 Parameter reference violation x X x 


10 Damage encountered 
04 System object damage state X 


44 Partial system object damage X 


1c Machine-dependent exception 
03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
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Exception 


22 


24 


2C 


2E 


32 


36 


38 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 Template value invalid 
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Operands 
1 2 3 Other 
X 
X X X 
X X X 
X X X 
X 
X X X 
Xx X X 
xX 
X 
X Xx X 
X 
X 
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Convert Decimal Form to Floating-Point (CVTDFFP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
107F Receiver Decimal exponent Decimal 
significand 


Operand 1: Floating-point variable scalar. 
Operand 2: Packed scalar or zoned scalar. 
Operand 3: Packed scalar or zoned scalar. 


Description: This instruction converts the decimal form of a floating-point value specified by a decimal 
exponent and a decimal significand to binary floating-point format, and places the result in the receiver 
operand. The decimal exponent (operand 2) and decimal significand (operand 3) are considered to 
specify a decimal form of a floating-point number. The value of this number is considered to be as 
follows: 


Value = S * (10**E) 
where: 


S = The value of the decimal significand operand. 
E = The value of the decimal exponent operand. 

* Denotes multiplication. 

** Denotes exponentiation. 


The decimal exponent must be specified as a decimal integer value; no fractional digit positions may 
be specified in its definition. The decimal exponent is a signed integer value specifying a power of 10 
which gives the floating-point value its magnitude. A decimal exponent value too large or too small to 
be represented in the receiver will result in the signaling of the appropriate floating-point overflow (hex 
OCQ6) or floating-point underflow (hex 0CO7) exception. 


The decimal significand must be specified as a decimal value with a single integer digit position and 
optional fractional digit positions. The decimal significand is a signed decimal value specifying 
decimal digits which give the floating-point value its precision. The significant digits of the decimal 
significand are considered to start with the leftmost nonzero decimal digit and continue to the right to 
the end of the decimal significand value. Significant digits beyond 7 for a short float receiver, and 
beyond 15 for a long float receiver exceed the precision provided for in the binary floating-point 
receiver. These excess digits do participate in the conversion to provide for uniqueness of the conver- 
sion as well as for proper rounding. 


The decimal form floating-point value specified by the decimal exponent and decimal significand oper- 
ands is converted to a binary floating-point number and rounded to the precision of the result field as 
follows: 


source values which, in magnitude M, are in the range where (10°*31-1) * 10**-31 <= M <= 
(10**31-1) *10** +31 are converted subject to the normal rounding error defined for the floating-point 
rounding modes. 


source values which, in magnitude M, are in the range where (10**31-1) * 10**-31 > M > (10**31-1) 
*40*°* +31 are converted such that the rounding error incurred on the conversion may exceed that 
defined above. For round to nearest, this error will not exceed by more than .47 units in the least 
significant digit position of the result in relation to the error that would be incurred for normal 
rounding. For the other floating-point rounding modes, this error will not exceed 1.47 units in the least 
significant digit position of the result. 


The converted and rounded value is then assigned to the floating-point receiver. 
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Exceptions 


Exception 1 2 3 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment violation 


03 Range 


x KK XK 
x KK XK 
x KK XK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation X X X 


0c Computation 
02 Decimal data X X 


06 Floating-point overflow X 


x< 


07 Floating-point underflow 


OD Floating-point inexact result X 


10 Damage encountered 
04 System object damage state X 
44 Partial system object damage . X 


1C Machine-dependent exception 


03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
02 Function check Xx 


22 Object access 
01 Object not found X X X 
02 Object destroyed 
03 Object suspended X X X 


08 object compressed X 


~< 
~< 
~< 


24 Pointer specification 
01 Pointer does not exist X X X 
02 Pointer type invalid X X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 Scalar type invalid X X X 


36 Space management 


01 space extension/truncation 
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Convert External Form to Numeric Value (CVTEFN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
1087 Receiver Source Mask 


Operand 1: Numeric variable scalar or data-pointer-defined numeric scalar. 
Operand 2: Character scalar or data-pointer-defined character scalar. 


Operand 3: Character(3) scalar, null, or data-pointer-defined character(3) scalar. 


ILE access 
CVTEFN ( 
var receiver : any numeric type; 
var receiver_attributes : aggregate; 
var source : aggregate; 
var source length : unsigned binary; 
var mask : aggregate 


Description: This instruction scans a character string for a valid decimal number in display format, 
removes the display character, and places the results in the receiver operand. The operation begins 
by scanning the character string value in the source operand to make sure it is a valid decimal number 
in display format. 


The character string defined by operand 2 consists of the following optional entries: 


¢ Currency symbol - This value is optional and, if present, must precede any sign and digit values. 
The valid symbol is determined by operand 3. The currency symbol may be preceded in the field 
by blank (hex 40) characters. 


* Sign symbol - This value is optional and, if present, may precede any digit values (a leading sign) 
or may follow the digit values (a trailing sign). Valid signs are positive (hex 4E) and negative (hex 
60). The sign symbol, if it is a leading sign, may be preceded by blank characters. If the sign 
symbol is a trailing sign, it must be the rightmost character in the field. Only one sign symbol is 
allowed. 


¢« Decimal digits - Up to 31 decimal digits may be specified. Valid decimal digits are in the range of 
hex FO through hex F9 (0-9). The first decimal digit may be preceded by blank characters (hex 40), 
but hex 40 values located to the right of the leftmost decimal digit are invalid. 


The decimal digits may be divided into two parts by the decimal point symbol: an integer part and a 
fractional part. Digits to the left of the decimal point are interpreted as integer values. Digits to the 
right are interpreted as a fractional values. If no decimal point symbol is included, the value is inter- 
preted as an integer value. The valid decimal point symbol is determined by operand 3. If the decimal 
point symbol precedes the leftmost decimal digit, the digit value is interpreted as a fractional value, 
and the leftmost decimal digit must be adjacent to the decimal point symbol. If the decimal point 
follows the rightmost decimal digit, the digit value is interpreted as an integer value, and the rightmost 
decimal digit must be adjacent to the decimal point. 


Decimal digits in the integer portion may optionally have comma symbols separating groups of three 
digits. The leftmost group may contain one, two, or three decimal digits, and each succeeding group 
must be preceded by the comma symbol and contain three digits. The comma symbol must be adja- 
cent to a decimal digit on either side. The valid comma symbol is determined by operand 3. 
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Decimal digits in the fractional portion may not be separated by commas and must be adjacent to one 
another. 


Examples of external formats follow. The following symbols are used. 


3 currency symbol 
decimal point 

comma 

D digit (hex FO-F9) 
blank (hex 40) 

+ positive sign 

- negative sign 


Format Comments 

$+DDDD.DD Currency symbol, leading sign, no comma separators 
DD,DDD- Comma symbol, no fraction, trailing sign 

-.DDD No integer, leading sign 

$DDD,DDD- No fraction, comma symbol, trailing sign 

$ + DD.DD Embedded blanks before digits 


Operand 3 must be a 3-byte character scalar. Byte 1 of the string indicates the byte value that is to be 
used for the currency symbol. Byte 2 of the string indicates the byte value to be used for the comma 
symbol. Byte 3 of the string indicates the byte value to be used for the decimal point symbol. If 
operand 3 is null, the currency symbol (hex 5B), comma (hex 6B), and decimal point (hex 4B) are used. 


If the syntax rules are violated, a conversion (hex 0C01) exception is signaled. If not, a zoned decimal 
value is formed from the digits of the display format character string. This number is placed in the 
receiver operand following the rules of a normal arithmetic conversion. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 Spacing addressing violation X X X 
02 Boundary alignment X X X 
03 Range X X X 
06 Optimized addressability invalid X X X 
08 Argument/parameter 
01 Parameter reference violation X X X 
0c Computation 
01 Conversion X 
0A Size X 
10 Damage encountered 
04 System object damage X X X X 
44 Partial system object damage X X X X 
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Exception 


1C 


20 


22 


24 


2E 


32 


36 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


02 Scalar attribute invalid 


Space management 


01 space extension/truncation 


Convert External Form to Numeric Value (CVTEFN) 


Operands 
1 2 3 Other 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X X 
X 
X 
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Convert Floating-Point to Decimal Form (CVTFPDF) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 - 
CVTFPDF Decimal exponent Decimal Source 

10BF significand 

CVTFPDFR Decimal exponent Decimal Source 

12BF significand 


Operand 1: Packed variable scalar or zoned variable scalar. 
Operand 2: Packed variable scalar or zoned variable scalar. 
Operand 3: Floating-point scalar. 


Description: This instruction converts a binary floating-point value to a decimal form of a floating-point 
value specified by a decimal exponent and a decimal significand, and places the result in the decimal 
exponent and decimal significand operands. 


The value of this number is considered to be as follows: 
Value = S * (10**E) 
where: 
S = The value of the decimal significand operand. 
E = The value of the decimal exponent operand. 
* Denotes multiplication. 
** Denotes exponentiation. ~d 


The decimal exponent must be specified as a decimal integer value. No fractional digit positions are 
allowed. It must be specified with at least five digit positions. The decimal exponent provides for 
containing a signed integer value specifying a power of 10 which gives the floating-point value its mag- 
nitude. 


The decimal significand must be specified as a decimal value with a single integer digit position and 
optional fractional digit positions. The decimal significand provides for containing a signed decimal 
value specifying decimal digit is which give the floating-point value its precision. The decimal 
significand is formed as a normalized value, that is, the leftmost digit position is nonzero for a nonzero 
source value. 


When the source contains a representation of a normalized binary floating-point number with decimal 
significand digits beyond the leftmost 7 digits for a short floating-point source or beyond the leftmost 15 
digits for a long floating-point source, the precision allowed for the binary floating-point source is 
exceeded. 


When the source contains a representation of a denormalized binary floating-point number, it may 
provide less precision than the precision of a normalized binary floating-point number, depending on 
the particular source value. Decimal significand digits exceeding the precision of the source are set as 
a result of the conversion to provide for uniqueness of conversion and are correct, except for rounding 
errors. These digits are only as precise as the floating-point calculations that produced the source 
value. The floating-point inexact result (nex OCOD) exception provides a means of detecting loss of 
precision in floating-point calculations. J 


The binary floating-point source is converted to a decimal form floating-point value and rounded to the 
precision of the decimal significand operand as follows: 
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The decimal significand is formed as a normalized value and the decimal exponent is set accord- 
ingly. 

For the nonround form of the instruction, the value to be assigned to the decimal significand is 
adjusted to the precision of the decimal significand, if necessary, according to the current float 
rounding mode in effect for the process. For the optional round form of the instruction, the decimal 
round algorithm is used for the precision adjustment of the decimal significand. The decimal round 
algorithm overrides the current floating-point rounding mode that is in effect for the process. 


Source values which, in magnitude M, are in the range where (10**31-1) * 10**-31 <= M <= 
(10**31-1) * 10** +31 are converted subject to the normal rounding error defined for the floating- 
point rounding modes and the optional round form of the instruction. 


source values which, in magnitude M, are in the range where (10**31-1) * 10**-31 > M > (10°*31-1) 
*10**+31 are converted such that the rounding error incurred on the conversion may exceed that 
defined above. For round to nearest and the optional round form of the instruction, this error will 
not exceed by more than .47 units in the least significant digit position of the result, the error that 
would be incurred for a correctly rounded result. For the other floating-point rounding modes, this 
error will not exceed 1.47 units in the least significant digit position of the result. 


If necessary, the decimal exponent value is adjusted to compensate for rounding. 


The converted and rounded value is then assigned to the decimal exponent and decimal 
significand operands. 


A size (nex OCOA) exception cannot occur on the assignment of the decimal exponent or the decimal 
significand values. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


The result of the operation is unpredictable for any type of overlap between the decimal exponent and 
decimal significand operands. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 Spacing addressing violation X X X 
02 Boundary alignment violation X X X 
03 Range X X X 
06 Optimized addressability invalid X X X 
08 Argument/parameter 
01 Parameter reference violation X X X 
0c Computation 
OC Invalid floating-point conversion X X 
OD Floating-point inexact result X 
10 Damage encountered 
04 System object damage state X 
44 Partial system object damage X 
1C Machine-dependent exception 
03 Machine storage limit exceeded X 
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Exception 


20 


22 


24 


2E 


32 


36 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


04 Scalar type invalid 


Space management 


01 space extension/truncation 


Convert Floating-Point to Decimal Form (CVTFPDF) 


Operands 
1 2 3 Other 
X 
X 
X X X 
X X xX 
X X X 
X 
X X X 
X X X 
X 
X X X 
X 
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Convert Hex to Character (CVTHC) 


Op Code (Hex) Operand 1 Operand 2 
1086 Receiver Source 


Operand 1: Character variable scalar. 
Operand 2: Character variable scalar. 


Description: Each hex digit (4-bit value) of the string value in the source operand is converted to a 
character (8-bit value) and placed in the receiver operand. 


Hex Digits Characters 
Hex 0-9 = Hex FQ-F9 
Hex A-F = Hex C1-C6 


The operation begins with the two operands left-adjusted and proceeds left to right until all the charac- 
ters of the receiver operand have been filled. If the source operand contains fewer hex digits than 
needed to fill the receiver, the excess characters are assigned a value of hex FO. If the source 
operand is too large, a /Jength conformance (hex 0C08) or an invalid operand length (hex 2AQA) excep- 
tion is signaled. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that 
the bytes of the receiver are each set with a value of hex FO. The effect of specifying a null substring 
reference for the receiver is that no result is set. 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment 
03 Range 


x KX KK KR 
x K K XK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation X xX 


le Computation 


08 Length conformance X 


10 Damage encountered 
04 System object damage state Xx X X 
44 Partial system object damage X X X 


1C Machine-dependent exception 
03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check xX 
02 Function check xX 
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Exception 


22 


24 


2E 


36 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Convert Hex to Character (CVTHC) 


Operands 
1 2 
X X 
X Xx 
X X 
X X 
X X 


Other 
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Convert MRJE to Character (CVTMC) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 
CVIMC Receiver Controls Source 

10AB 

CVTMCB Branch options Receiver Controls Source Branch targets 
1CAB 

CVTMCI Indicator Receiver Controls Source Indicator targets 
18AB options 


Operand 7: Character variable scalar. 
Operand 2: Character(6) variable scalar (fixed-length). 
Operand 3: Character scalar. 


Operand +5: 


° Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
CVIMC ( 
var receiver : aggregate; 
receiver_length : unsigned binary; 
var controls : aggregate; 
var source : aggregate; 
source_length : unsigned binary; 
var return_code : signed binary 
) 
The return_code will be set as follows: 
Return Code Meaning 
-1 Receiver Overrun, 
8 Source Exhausted. 


Description: This instruction converts a character string from the MRJE (MULTI-LEAVING remote job 
entry) compressed format to character format. The operation converts the source (operand 3) from the 
MRJE compressed format to character format under control of the controls (operand 2) and places the 
results in the receiver (operand 1). 


The source and receiver operands must both be character strings. The source operand cannot be 
specified as either a signed or unsigned immediate value. 


The controis operand must be a character scalar that specifies additional information to be used to 
control the conversion operation. It must be at least 6 bytes in length and have the following format: 


e Controls operand Char(6) 
— Receiver offset Bin(2) 
— Source offset Bin(2) 
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— Algorithm modifier Char(‘) 
— Receiver record length Char(1) 


As input to the instruction, the source offset and receiver offset fields specify the offsets where bytes of ail 
the source and receiver operands are to be processed. If an offset is equal to or greater than the 

length specified for the operand it corresponds to (it identifies a byte beyond the end of the operand), a 
template value invalid (hex 3801) exception is signaled. As output from the instruction, the source 

offset and receiver offset fields specify offsets that indicate how much of the operation is complete 

when the instruction ends. 


The algorithm modifier has the following valid values: 
e Hex 00 = Do not move SRCBs (sub record control bytes) from the source into the receiver. 


¢ Hex 01 = Move SRCBs from the source into the receiver. 


The receiver record length value specifies the record length to be used to convert source records into 
the receiver operand. This length applies to only the string portion of the receiver record and does not 
include the optional SRCB field. If a receiver record length of 0 is specified, a template value invalid 
(hex 3801) exception is signaled. 


Only the first 6 bytes of the controls operand are used. Any excess bytes are ignored. 


The operation begins by accessing the bytes of the source operand at the location specified by the 
source offset. This is assumed to be the start of a record. The bytes of the records in the source 
operand are converted into the receiver operand at the location specified by the receiver offset 
according to the following algorithm. 


The first byte of the source record is considered to be an RCB (record control byte) that is to be 
ignored during conversion. ) 


The second byte of the source record is considered to be an SRCB. If an algorithm modifier of value 
hex 00 was specified, the SRCB is ignored. If an algorithm modifier of value hex 01 was specified, the 
SRCB is copied into the receiver. 


The strings to be built in the receiver record are described in the source after the SRCB by one or 
more SCBs (string control bytes). 


The format of the SCBs in the source are as follows: 
ok 1 jjjJjj 


The bit meanings are: 


Bit Value Meaning 
o 0 End of record;the EOR SCB is hex 00. 
1 All other SCBs. 
k 0 The string is compressed. 
1 The string is not compressed. 
| Fork = 0: 
0 Blanks (hex 40s) have been deleted. 
1 Nonblank characters have been deleted. The next character 
in the data stream is the specimen character. 
Fork = 1: 
This bit is part of the length field for length of uncompressed - 
data. 
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Bit Value Meaning 

iii Number of characters that have been deleted if k = 0. The 
value can be 1-31. 

ji Number of characters to the next SCB (no compression) if 
k=1. The value can be 1-63. 


The uncompressed (nonidentical bytes) follow the SCB in the 
data stream. 


A length of 0 encountered in an SCB results in the signaling of a conversion (hex 0C01) exception. 


Strings of blanks or nonblank identical characters described in the source record are repeated in the 
receiver the number of times indicated by the SCB count value. 


Strings of nonidentical characters described in the source record are moved into the receiver for the 
length indicated by the SCB count value. 


When an EOR (end of record) SCB (hex 00) is encountered in the source, the receiver is padded with 
blanks out to the end of the current record. 


If the converted form of a source record is larger than the receiver record length, the instruction is 
terminated by signaling a /Jength conformance (hex 0CO8) exception. 


If the end of the source operand is not encountered, the operation then continues by reapplying the 
above algorithm to the next record in the source operand. 


If the end of the source operand is encountered (whether or not in conjunction with a record boundary, 
EOR SCB in the source), the instruction ends with a resultant condition of source exhausted. The 
receiver offset locates the byte following the last fully converted record in the receiver. The source 
offset locates the byte following the last source record for which conversion is complete. The value of 
the remaining bytes in the receiver after the last converted record are unpredictable. 


If the converted form of a record cannot be completely contained in the receiver, the instruction ends 
with a resultant condition of receiver overrun. The receiver offsert locates the byte following the last 
fully converted record in the receiver. The source offset locates the byte following the last source 
record for which conversion is complete. The value of the remaining bytes in the receiver after the last 
converted record is unpredictable. 


If the source exhausted and the receiver overrun conditions occur at the same time, the source 
exhausted condition is recognized first. In this case, the receiver offset may contain a value equal to 
the length specified for the receiver which causes an exception to be signaled on the next invocation of 
the instruction. The processing performed for the source exhausted condition provides for this case if 
the instruction is invoked multiple times with the same controls operand template. When the receiver 
overrun condition is the resultant condition, the source always contains data that can be converted. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


Any form of overlap between the operands on this instruction yields unpredictable results in the 
receiver operand. 
Resultant Conditions 


e Source exhausted - All full records in the source operand have been converted into the receiver 
operand. 


e Receiver overrun - An overrun condition in the receiver operand was detected prior to processing 
all of the bytes in the source operand. 
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Exceptions 


Exception 


06 


08 


0c 


10 


20 


22 


24 


2C 


2E 


32 


36 


38 


Addressing 

01 Spacing addressing violation 
02 Boundary alignment violation 
03 Range 

06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Computation 
01 Conversion 


08 Length conformance 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 Template value invalid 


Convert MRJE to Character (CVTMC) 


Operands 
1 2 3 Other 


X X X 
X X X 
X X X 
X X X 
X X X 
X 
X 
X 
X 
X 
X 
X 
X X X 
X X X 
Xx X X 
X 
X X X 
X X X 
X 
X 
xX X X 
X 
X 
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Convert Numeric to Character (CVTNC) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
10A3 Receiver Source Attributes 


Operand 1: Character variable scalar or data-pointer-defined character scalar. 
Operand 2: Numeric scalar or data-pointer-defined numeric scalar. 
Operand 3: Character(7) scalar or data-pointer-defined character(7) scalar. 


Description: The source numeric value (operand 2) is converted and copied to the receiver character 
string (operand 1). The receiver operand is treated as though it had the attributes supplied by operand 
3. Operand 1, when viewed in this manner, receives the numeric value of operand 2 following the 
rules of the Copy Numeric Value instruction. 


The format of operand 3 is as follows: 
e Scalar attributes Char(7) 


— Scalar type Char(1) 


Hex 00 = Signed binary 
Hex 01 = Floating-point 
Hex 02 = Zoned decimal 


Hex 03 Packed decimal 
Hex OA = Unsigned binary 
— Scalar length Bin(2) 
If binary: 
- Length (L) (where L = 2 or 4) Bits 0-15 
If floating-point: 
- Length (where L = 4 or 8) Bits 0-15 
If zoned decimal or packed decimal: 
- Fractional digits (F) Bits 0-7 
- Total digits (T) Bits 8-15 
(where 1<T <31 and O<F<T) 
— Reserved (binary 0) Bin(4) 


The byte length of operand 1 must be large enough to contain the numeric value described by operand 
3. If it is not large enough, a scalar value invalid (hex 3203) exception is signaled. If it is larger than 
needed, the numeric value is placed in the leftmost bytes and the unneeded rightmost bytes are 
unchanged by the instruction. 


If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 
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Exception 


08 


OC 


20 


22 


24 


2E 


32 


36 


01 Spacing addressing violation 
02 Boundary alignment 

03 Range 

04 External data object not found 


06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Computation 

02 Decimal data 

06 Floating-point overflow 

07 Floating-point underflow 

09 Floating-point invalid operand 
0A Size 

OC Invalid floating-point conversion 
0D Floating-point inexact result 
Damage encountered 

04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource contro! limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 
02 Scalar attribute invalid 


03 Scalar value invalid 


Space management 


01 space extension/truncation 


Convert Numeric to Character (CVTNC) 


Operands 

1 2 3 Other 
X X X 

X X X 

X X X 

X X X 

X X X 

X X X 


X 
X 
X 

X 
X 
X 
X 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X X 
X 
X 
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Convert SNA to Character (CVTSC) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-6] 
CVTSC Receiver Controls Source 

{0DB 

CVTSCB Branch options Receiver Controls Source Branch targets 
1CDB 

CVTSCI Indicator Receiver Controls Source Indicator targets 
18DB options 


Operand 1: Character variable scalar. 
Operand 2: Character(14) variable scajar (fixed length). 
Operand 3: Character scalar. 


Operand 4-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
CVTSC ( 
var receiver : aggregate; 
receiver_length : unsigned binary; 
var controls : aggregate; 
var source : aggregate; 
source length : unsigned binary; 
var return_code : signed binary 
) 
The return_code will be set as follows: 
Return Code Meaning 
-1 Receiver Overrun. 
3] Source Exhausted. 
1 Escape Code Encountered 


Description: This instruction converts a string value from SNA (systems network architecture) format 
to character. The operation converts the source (operand 3) from SNA format to character under 
control of the controls (operand 2) and places the result into the receiver (operand 1). 


~ 


The source and receiver operands must both be character strings. The source operand may not be 
specified as an immediate operand. 


The controls operand must be a character scalar that specifies additional information to be used to 
control the conversion operation. It must be at least 14 bytes in length and have the following format: 
« Controls operand base template Char(14) 


— Receiver offset Bin{2) 
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— Source offset Bin(2) 
— Algorithm modifier Char(1) | 
— Receiver record Jength Char(1) a 
— Record separator Char(1) 
— Prime compression Char(1) 
— Unconverted receiver record bytes Char(‘) 
— Conversion status Char(2) 
— Unconverted transparency string bytes Char(1) 
— Offset into template to translate table Bin(2) 
¢ Controls operand optional template extension Char(64) 
— Record separator translate table Char(64) 


Upon input to the instruction, the source offset and receiver offset fields specify the offsets where bytes 
of the source and receiver operands are to be processed. If an offset is equal to or greater than the 
length specified for the operand it corresponds to (it identifies a byte beyond the end of the operand), a 
template value invalid (hex 3801) exception is signaled. As output from the instruction, the source 
offset and receiver offset are set to specify offsets that indicate how much of the operation is complete 
when the instruction ends. 


The algorithm modifier specifies the optional functions to be performed. Any combination of functions 
not preciuded by the bit definitions below is valid except that at least one of the functions must be 
specified. All algorithm modifier bits cannot be zero. Specification of an invalid algorithm modifier 


value results in a template value invalid (hex 3801) exception. The meaning of the bits in the algorithm { : 
modifier is the following: . ) 
Bits Meaning 
0 0 = Do not perform decompression. !nterpret a source character value of hex 00 as null. 
1 = Perform decompression. Interpret a source character value of hex 00 as a record separator. 
1-2 00 = No record separators in source, no blank padding. Do not perform data transparency conver- 
sion. 


01 = Reserved. 

10 = Record separators in source, perform blank padding. Do not perform data transparency conver- 
sion. 

Record separators in source, perform blank padding. Perform data transparency conversion. 


11 


3-4 00 = Do not put record separators into receiver. 
01 = Move record separators from source to receiver (allowed only when bit 1 = 1) 
10 = Translate record separators from source to receiver (allowed only when bit 1 = 1) 
11 = Move record separator from controls to receiver. 


5-7 Reserved 


The receiver record length value specifies the record length to be used to convert source records into 
the receiver operand. This length applies only to the data portion of the receiver record and does not 
include the optional record separator. Specification of a receiver record length of zero results in a 
template value invalid (hex 3801) exception. The receiver record length value is ignored if no record 
separator processing is requested in the algorithm modifier. 


The record separator value specifies the character that is to precede the converted form of each record 

in the receiver. The record separator character specified in the controls operand is used only for the | 
case where the move record separator from controls to receiver function is specified in the a/gorithm J 
modifier or where a missing record separator in the source is detected. 
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The prime compression value specifies the character to be used as the prime compression character 
when performing decompression of the SNA format source data to character. It may have any value. 
The prime compressien value is ignored if the perform decompression function is not specified in the 
algorithm modifier. 


The unconverted receiver record bytes value specifies the number of bytes remaining in the current 
receiver record that are yet to be set with converted bytes from the source. 


When record separator processing is specified in the algorithm modifier, this value is both input to and 
output from the instruction. On input, a value of hex 00 means it is the start of processing for a new 
record, and the initial conversion step is yet to be performed. This indicates that for the case where a 
function for putting record separators into the receiver is specified in the algorithm modifier, a record 
separator character has yet to be placed in the receiver. On input, a nonzero value less than or equal 
to the receiver record length specifies the number of bytes remaining in the current receiver record 
that are yet to be set with converted bytes from the source. This value is assumed to be the valid 
count of unconverted receiver record bytes relative to the current byte to be processed in the receiver 
as located by the receiver offset field. As such, it is used to determine the location of the next record 
boundary in the receiver operand. This value must be less than or equal to the receiver record length 
value; otherwise, a template value invalid (hex 3801) exception is signaled. On output, this field is set 
with a value as defined above which describes the number of bytes of the current receiver record not 
yet containing converted data. 


When record separator processing is not specified in the algorithm modifier, this value is ignored. 


The conversion status field specifies status information for the operation to be performed. The 
meaning of the bits in the conversion status is the following: 


Bits Meaning 
0 0 = No transparency string active. 


1 = Transparency string active. Unconverted transparency string bytes value contains the 
remaining string length. 


1-15 Reserved 


This field is both input to and output from the instruction. It provides for checkpointing the conversion 
status over successive executions of the instruction. 


If the conversion status indicates transparency string active, but the algorithm modifier does not specify 
perform data transparency conversion, a template value invalid (hex 3801) exception is signaled. 


The unconverted transparency string bytes field specifies the number of bytes remaining to be con- 
verted for a partially processed transparency string in the source. 


When perform data transparency conversion is specified in the algorithm modifier, the unconverted 
transparency string bytes field can be both input to and output from the instruction. 


On input, when the no transparency string active status is specified in the conversion status, this value 
is ignored. 


On input, when transparency string active status is specified in the conversion status, this value con- 
tains a count for the remaining bytes to be converted for a transparency string in the source. A value 
of hex 00 means the count field for a transparency string is the first byte of data to be processed from 
the source operand. A value of hex 01 through hex FF specifies the count of the remaining bytes to be 
converted for a transparency string. This value is assumed to be the valid count of unconverted trans- 
parency string bytes relative to the current byte to be processed in the source as located by the source 
offset field. 
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On output, this value is set if necessary along with the transparency string active status to describe a 

partially converted transparency string. A value of hex 00 will be set if the count field is the next byte 

to be processed for a‘transparency string. A value of hex 01 through hex FF specifying the number of } 
remaining bytes to be converted for a transparency string, will be set if the count field has already a 
been processed. 


When do not perform data transparency conversion is specified in the algorithm modifier, the uncon- 
verted transparency string bytes value is ignored. 


The offset into template to translate table value specifies the offset from the beginning of the template 
to the record separator translate table. This value is ignored unless the translate record separators 
from source to receiver function is specified in the algorithm modifier. 


The record separator translate table value specifies the translate table to be used in translating record 
separators specified in the source to the record separator value to be placed into the receiver. It is 
assumed to be 64 bytes in length, providing for translation of record separator values of from hex 00 to 
hex 3F. This translate table is used only when the translate record separators from source to receiver 
function is specified in the algorithm modifier. See the record separator conversion function under the 
conversion process described below for more detail on the usage of the translate table. 


Only the first 14 bytes of the controls operand base template and the optional 64-byte extension area 
specified for the record separator translate table are used. Any excess bytes are ignored. 


The description of the conversion process is presented as a series of separately performed steps, 
which may be selected in allowable combinations to accomplish the conversion function. It is pre- 
sented this way to allow for describing these functions separately. However, in the actual execution of 
the instruction, these functions may be performed in conjunction with one another or separately, 
depending upon which technique is determined to provide the best implementation. 2 


The operation is performed either on a record-by-record basis, record processing, or on a nonrecord 
basis, string processing. This is determined by the functions selected in the a/gorithm modifier. Speci- 
fying the record separators in source, perform blank padding or move record separator from controls to 
receiver indicates record processing is to be performed. If neither of these functions is specified, in 
which case decompression must be specified, it indicates that string processing is to be performed. 


The operation begins by accessing the bytes of the source operand at the location specified by the 
source offset. 


When record processing is specified, the source offset may locate a point at which processing of a 
partially converted record is to be resumed or processing for a full record is to be started. The uncon- 
verted receiver record bytes field indicates whether conversion processing is to be started with a 
partial or a full record. Additionally, the transparency string active indicator in the conversion status 
field indicates whether conversion of a transparency string is active for the case of resumption of proc- 
essing for a partially converted record. The conversion process is started by completing the conver- 
sion of a partial source record if necessary before processing the first full source record. 


When string processing is specified, the source offset is assumed to locate the start of a compression 
entry. 


When during the conversion process the end of the receiver operand is encountered, the instruction 
ends with a resultant condition or receiver overrun. 


When record processing is specified in the algorithm modifier, this check is performed at the start of | 
conversion for each record. A source exhausted condition would be detected before a receiver overrun - 
condition if there is no source data to convert. If the receiver operand does not have room for a full = 

record, the receiver overrun condition is recognized. The instruction is terminated with status in the 
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controls operand describing the last completely converted record. For receiver overrun, partial conver- 
sion of a source record is not performed. 


When string processing is specified in the algorithm modifier, then decompression must be specified 
and the decompression function described below defines the detection of receiver overrun. 


When during the conversion process the end of the source operand is encountered, the instruction 
ends with a resultant condition of source exhausted. See the description of this condition in the con- 
version process described below to determine the status of the controls operand values and the con- 
verted bytes in the receiver for each case. 


When string processing is specified, the bytes accessed from the source are converted on a string 
basis into the receiver operand at the location specified by the receiver offset. In this case, the decom- 
pression function must be specified and the conversion process is accomplished with just the decom- 
pression function defined below. 


When record processing is specified, the bytes accessed from the source are converted one record at 
a time into the receiver operand at the location specified by the receiver offset performing the functions 
specified in the algorithm modifier in the sequence defined by the following algorithm. 


Record separator conversion is performed as requested in the algorithm modifier during the initial 
record separator processing performed as each record is being converted. This provides for control- 
ling the setting of the record separator value in the receiver. 


When the record separators in source option is specified, the following algorithm is used to locate 
them. A record separator is recognized in the source when a character value less than hex 40 is 
encountered. When do not perform decompression is specified, a source character value of hex 00 is 
recognized as a null value rather than as a record separator. In this case, the processing of the 
current record continues with the next source byte and the receiver is not updated. When perform data 
transparency conversion is specified, a character value of hex 35 is recognized as the start of a trans- 
parency string rather than as a record separator. 


If the do not put record separators into the receiver function is specified, the record separator, if any, 
from the source record being processed is removed from the converted form of the source record and 
will not be placed in the receiver. 


lf the move record separators from the source to the receiver function is specified, the record separator 
from the source record being processed is left as is in the converted form of the source record and will 
be placed in the receiver. 


If the translate record separators from the source to the receiver function is specified, the record sepa- 
rator from the source record being processed is translated using the specified translate table, replaced 
with its translated value in the converted form of the source record and, will be placed in the receiver. 
The translation is performed as in the translate instruction with the record separator value serving as 
the source byte to be translated. It is used as an index into the specified translate table to select the 
byte in the translate table that contains the value to which the record separator is to be set. If the 
selected translate table byte is equal to hex FF, it is recognized as an escape code. The instruction 
ends with a resultant condition of escape code encountered, and the controls operand is set to 
describe the conversion status as of the processing completed just prior to the conversion step for the 
record separator. If the selected translate table byte is not equal to hex FF, the record separator in the 
converted form of the record is set to its value. 


If the move record separator from controls to receiver function is specified, the controls record sepa- 
rator value is used in the converted form of the source record and will be placed into the receiver. 
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When the record separators in source do blank padding function is requested, an assumed record sep- 
arator will be used if a record separator is missing in the source data. In this case, the controls record 
separator character is used as the record separator to precede the converted record if record separa- 
tors are to be placed in the receiver. The conversion process continues, bypassing the record sepa- 
rator conversion step that would normally be performed. The condition of a missing record separator 
is detected when during initial processing for a full record, the first byte of data is not a record sepa- 
rator character. 


Decompression is performed if the function is specified in the a/gorithm modifier. This provides for 
converting strings of duplicate characters in compressed format in the source back to their full size in 
the receiver. Decompression of the source data is accomplished by concatenating together character 
strings described by the compression strings occurring in the source. The source offset value is 
assumed to locate the start of a compression string. Processing of a partial decompressed record is 
performed if necessary. 


The character strings to be built into the receiver are described in the source by one or more com- 
pression strings. Compression strings are comprised of an SCB (string control byte) possibly followed 
by one or more bytes of data related to the character string to be built into the receiver. 


The format of an SCB and the description of the data that may follow it is as follows: 
« SCB Char(1) 
— Control Bits 0-1 


00 = n nonduplicate characters are between this SCB and the next one; where n is the value 
of the count field (1-63). 

01 = Reserved. 

10 = This SCB represents n deleted prime compression characters; where n is the value of the 
count field (1-63). The next byte is the next SCB. 

11 = This SCB represents n deleted duplicate characters; where n is the value of the count 
field (1-63). The next byte contains a specimen of the deleted characters. The byte fol- 
lowing the specimen character contains the next SCB. 


— Count Bits 2-7 


This contains the number of characters that have been deleted for a prime or duplicate string, 
or the number of characters to the next SCB for a nonduplicate string. A count value of Zero is 
invalid and results in the signaling of a conversion (hex 0C01) exception. 


Strings of prime compression characters or duplicate characters described in the source are repeated 
in the decompressed character string the number of times indicated by the SCB count value. 


Strings of nonduplicate characters described in the source record are formed into a decompressed 
character string for the length indicated by the SCB count value. 


If the end of the source is encountered prior to the end of a compression string, a conversion (hex 
0C01) exception is signaled. 


When record processing is specified, decompression is performed one record at a time. In this case, a 
conversion (hex 0C01) exception is signaled if a compression string describes a character string that 
would span a record boundary in the receiver. If the source contains record separators, the case of a 
missing record separator in the source is detected as defined under the initial description of the con- 
version process. Record separator conversion, as requested in the a/gorithm modifier, is performed as 
the initial step in the building of the decompressed record. A record separator to be placed into the 
receiver is in addition to the data to be converted into receiver for the length specified in the receiver 
record length field. The decompression of compression strings from the source continues until a 
record separator character for the next record is recognized when the source contains record separa- 
tors, or until the decompressed data required to fill the receiver record has been processed or the end 
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of the source is encountered whether record separators are in the source or not. Transparency strings 
encountered in the decompressed character string are not scanned for a record separator value. If the 
end of the source is encountered, the data decompressed to that point appended to the optional record 
separator for this record forms a partial decompressed record. Otherwise, the decompressed char- 
acter strings appended to the optional record separator for this record form the decompressed record. 
The conversion process then continues for this record with the next specified function. 


When string processing is specified, decompression is performed on a compression string basis with 
no record oriented processing implied. The conversion process for each compression string from the 
source is completed by placing the decompressed character string into the receiver. The conversion 
process continues decompressing compression strings from the source until the end of the source or 
the receiver is encountered. When the end of the source operand is encountered, the instruction ends 
with a resultant condition of source exhausted. When a character string cannot be completely con- 
tained in the receiver, the instruction ends with a resultant condition of receiver overrun. For either of 
the above ending conditions, the controls operand is updated to describe the status of the conversion 
operation as of the last completely converted compression entry. Partial conversion of a compression 
entry is not performed. 


Data transparency conversion is performed if perform data transparency conversion is specified in the 
algorithm modifier. This provides for correctly identifying record separators in the source even if the 
data for a record contains value that could be interpreted as record separator values. Processing of 
active transparency strings is performed if necessary. 


A nontransparent record is built by appending the nontransparent and transparent data converted from 
the record to the record separator for the record. The nontransparent record may be produced from 
either a partial record from the source or a full record from the source. This is accomplished by first 
accessing the record separator for a full record. The case of a missing record separator in the source 
is detected as defined under the initial description of the conversion process. Record separator con- 
version as requested in the algorithm modifier is performed if it has not already been performed by a 
prior step; the rest of the source record is scanned for values of less than hex 40. 


A value greater than or equal to hex 40 is considered nontransparent data and is concatenated onto 
the record being built as is. 


A value equal to hex 35 identifies the start of a transparency string. A transparency string is com- 
prised of 2 bytes of transparency control information followed by the data to be made transparent to 
scanning for record separators. The first byte has a fixed value of hex 35 and is referred to as the TRN 
(transparency) control character. The second byte is a 1-byte hexadecimal count, a value remaining 
from 1 to 255 decimal, of the number of bytes of data that follow and is referred to as the TRN count. A 
TRN count of zero is invalid and causes a conversion (hex 0C01) exception. This contains the length of 
the transparent data and does not include the TRN control information length. The transparent data is 
concatenated to the nontransparent record being built and is not scanned for record separator charac- 
ters. 


A value equal to hex 00 is recognized as the record separator for the next record only when perform 
decompression is specified in the algorithm modifier. In this case, the nontransparent record is com- 
plete. When do not perform decompression is specified in the algorithm modifier, a value equal to hex 
00 is ignored and is not included as part of the nontransparent data built for the current record. | 


A value less than hex 40 but not equal to hex 35 is considered to be the record separator for the next 
record, and the forming of the nontransparent record is complete. 


The building of the nontransparent record is completed when the length of the data converted into the 
receiver equals the receiver record length if the record separator for the next record is not encount- 
ered prior to that point. 
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If the end of the source is encountered prior to completion of building the nontransparent record. the 
nontransparent record built up to this point is placed in the receiver and the instruction ends with a 

resultant condition of source exhausted. The controls operand is updated to describe the status for the ) 
partially converted record. This includes describing a partially converted transparency string, if neces- 
sary, by setting the active transparency string status and the unconverted transparency string bytes 

field. 


If the building of the nontransparent record is completed prior to encountering the end of the source, 
the conversion process continues with the blank padding function described below. 


k padding is performed if the function is specified in the algorithm modifier This provides for 
expanding out to the size specified by the receiver record length the source records for which trailing 
blanks have been truncated. The padded record may be produced from either a partial record from 
the source or a full record from the source. 


The record separator for this record is accessed. The case of a missing record separator in the 
source is detected as defined under the initial description of the conversion process. Record separator 
conversion as requested in the a/gorithm modifier, is performed if it has not already been performed by 
a prior step. 


The nontruncated data, if any, for the record is appended to the optional record separator for the 
record. The nontruncated data is determined by scanning the source record for the record separator 
for the next record. This scan is concluded after processing enough data to completely fill the receiver 
record or upon encountering the record separator for the next record. The data processed prior to 
concluding the scan is considered the nontruncated data for the record. 


The blanks, if any, required to pad the record out to the nontruncated data for the record, concluding 
the forming of the padded record. ' 


If the end of the source is encountered during the forming of the padded record, the data processed up 
to that point, appended to the optional record separator for the record, is placed into the receiver and 
the instruction ends with a resultant condition of source exhausted. The controls operand is updated to 
describe the status of the partially converted record. 


If the forming of the padded record is concluded prior to encountering the end of the source, the con- 
version of the record is completed by placing the converted form of the record into the receiver. 


At this point, either conversion of a source record has been completed or conversion has been inter- 
rupted due to detection of the source exhausted or receiver overrun condition. For record processing, if 
neither of the above conditions has been detected either during conversion of or at completion of con- 
version for the current record, the conversion process continues On the next source record with the 
decompression function described above. 


At completion of the instruction, the receiver offset locates the byte following the last converted byte in 
the receiver. The vaiue of the remaining bytes in the receiver after the last converted byte are unpre- 
dictable. The source offset |ocates the byte following the last source byte for which conversion was 
completed. When record processing is specified, the unconverted receiver record bytes field specifies 
the length of the receiver record bytes not yet containing converted data. When perform data transpar- 
ency conversion is specified in the algorithm modifier, the conversion status indicates whether conver- 
sion of a transparency string was active and the unconverted transparency string bytes field specifies 
the length of the remaining bytes to be processed for an active transparency string. 


This instruction does not provide support for compression entries in the source describing data that | 
would span records in the receiver. SNA data from some systems may violate this restriction and as aa 
such be incompatible with the instruction. A provision can be made to avoid this incompatibility by 

performing the conversion of the SNA data through two invocations of this instruction. The first invoca- 
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tion would specify decompression with no record separator processing. The second invocation would 
specify record separator processing with no decompression. This technique provides for separating the 
decompression step from record separator processing; thus, the incompatibility is avoided. 


This instruction can end with the escape code encountered condition. In this case, it is expected that 
the user of the instruction will want to do some speciai processing for the record separator causing the 
condition. In order to resume execution of the instruction, the user will have to set the appropriate 
value for the record separator into the receiver and update the controls operand source offset and 
receiver offset fields correctly to provide for restarting processing at the right points in the receiver and 
source operands. 


For the special case of a tie between the source exhausted and receiver overrun conditions, the source 
exhausted condition is recognized first. That is, when source exhausted is the resultant condition, the 
receiver may also be full. In this case, the receiver offset may contain a value equal to the length 
specified for the receiver, which would cause an exception to be detected on the next invocation of the 
instruction. The processing performed for the source exhausted condition should provide for this case 
if the instruction is to be invoked multiple times with the same controls operand template. When the 
receiver overrun condition is the resultant condition, the source will always contain data that can be 
converted. 


This instruction will, in certain cases, ignore what would normally have been interpreted as a record 
separator value of hex 00. This applies (hex 00 is ignored) for the special case when do not perform 
decompression and record separators in source are specified in the algorithm modifier. Note that this 
does not apply when perform decompression is specified, or when do not perform decompression and 
no record separators in source and move record separator from controls to receiver are specified in the 
algorithm modifier. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


Any form of overlap between the operands on this instruction yields unpredictable results in the 
receiver operand. 


Resultant Conditions 


e Source exhausted-The end of the source operand is encountered and no more bytes from the 
source can be converted. 


e Receiver overrun-An overrun condition in the receiver operand is detected before all of the bytes in 
the source operand have been processed. 


e« Escape code encountered-A record separator character is encountered in the source operand that 
is to be treated as an escape code. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Spacing addressing violation 

02 Boundary alignment violation 
03 Range 

06 Optimized addressability invalid 


x KK XK 
x KK XK 
x KK XK 


08 Argument/parameter 


01 Parameter reference violation X D4 X 
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Exception 


OC 


1C 


20 


22 


24 


2C 


2E 


32 


36 


38 


Computation 


01 Conversion 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 Template value invalid 


Convert SNA to Character (CVTSC) 


Operands 
1 2 3 Other 
X 
X 
X 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X xX 
X X X 
X 
X 
xX X X 
X 
X 
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Copy Bits Arithmetic (CPYBTA) 


Op Code (Hex) | Operand 1 Operand 2 Operand 3 Operand 4 
102C Receiver Source Offset Length 


Operand ?/: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 2: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 3: Signed or unsigned binary immediate. 
Operand 4: Signed or unsigned binary immediate. 


Description: This instruction copies the signed bit string source operand starting at the specified 
offset for a specified length right adjusted to the receiver and pads on the left with the sign of the bit 
string source. 


The selected bits from the source operand are treated as an signed bit string and copied to the 
receiver value. 


The source operand can be character or numeric. The leftmost bytes of the source operand are used 
in the operation. The source operand is interpreted as a bit string with the bits numbered left to right 
from 0 to the total number of bits in the string minus 1. 


The offset operand indicates which bit of the source operand is to be copied; with a offset of zero indi- 
cating the leftmost bit of the leftmost byte of the source operand. 


The length operand indicates the number of bits that are to be copied. 


lf the sum of the offset plus the length exceed the length of the source an invalid operand length (hex. 
2A0A) exception will be raised. 


Limitations: The length of the receiver cannot exceed four bytes. 
The offset must have a non-negative value. 


The length operand must be an immediate value between 1 and 32. 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Spacing addressing violation X X 
02 Boundary alignment violation Xx X 
03 Range X X 
06 Optimized addressability invalid xX X 
08 Argument/parameter 
01 Parameter reference violation xX X 
10 Damage encountered 
04 System object damage state X 
44 Partial system object damage X 
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Exception 


1C 


20 


22 


24 


2E 


36 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Copy Bits Arithmetic (CPYBTA) 


Operands 


1 2 3 4 Other 


X 
X 
X 
X X 
X X 
X 
X X 
X X 
X 
X 
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Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
101C Receiver Source Offset Length 


Operand ?: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 2: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 3: Signed or unsigned binary immediate. 
Operand 4: Signed or unsigned binary immediate. 


Description: Copies the unsigned bit string source operand starting at the specified offset for a speci- 
fied length to the receiver. 


If the receiver is shorter than the length, the left most bits are removed to make the source bit string 
conform to the length of the receiver. No exceptions are generated when truncation occurs. 


The selected bits from the source operand are treated as an unsigned bit string and copied right 
adjusted to the receiver and padded on the left with binary zeros. 


The source operand can be character or numeric. The leftmost bytes of the source operand are used 
in the operation. The source operand is interpreted as a bit string with the bits numbered left to right 
from QO to the total number of bits in the string minus 1. 


The offset operand indicates which bit of the source operand is to be copied, with a offset of zero indi- 
cating the leftmost bit of the leftmost byte of the source operand. 


The length operand indicates the number of bits that are to be copied. 


If the sum of the offset plus the length exceed the length of the source an invalid operand length (hex 
2A0A) exception will be signaled. 


Limitations: The length of the receiver cannot exceed four bytes. 
The offset must have a non-negative value. 


The length operand must be an immediate value between 1 and 32. 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Spacing addressing violation X Xx 
02 Boundary alignment violation xX X ‘ 
03 Range X X 
06 Optimized addressability invalid X X 
08 Argument/parameter 
01 Parameter reference violation X X X X 
10 Damage encountered 
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Exception 


1C 


20 


22 


24 


2E 


36 


04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Copy Bits Logical (CPYBTL) 


Operands 

1 2 3 4 Other 
X 
x 
X 
X 
X 

X X 

X X 
X 

X X 

X X 
X 
X 
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Copy Bits with Left Logical Shift (CPYBTLLS) 


Copy Bits with Left Logical Shift (CPYBTLLS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
102F Receiver Source Shift control 


Operand ?: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 
Operand 3: Character(2) scalar (fixed length) or unsigned binary(2) scalar. 


Description: This instruction copies the bit string value of the source operand to the bit string defined 
by the receiver operand with a left logical shift of the source bit string value under control of the shift 
control operand. 


The operation results in copying the shifted bit string value of the source to the bit string of the 
receiver while padding the receiver with bit values of 0 and truncating bit values of the source as is 
appropriate for the specific operation. 


No indication is given of truncation of bit values from the shifted source value. This is true whether the 
values truncated are O or 1. 


The operation is performed such that the bit string of the source is considered to be extended on the 
left and right by an unlimited number of bit string positions of value 0. Additionally, a receiver bit 
string view (window) with the attributes of the receiver is considered to overlay this conceptual bit 
string value of the source starting at the leftmost bit position of the original source value. A left logical 
shift of the conceptual bit string value of the source is then performed relative to the receiver bit string 
view according to the shift criteria specified in the shift control operand. After the shift, the bit string 
value then contained within the receiver bit string view is copied to the receiver. 


The source and the receiver can be either character or numeric. Any numeric operands are inter- 
preted as logical character strings. Due to the operation being treated as a character string operation, 
the source operand may not be specified as a signed immediate operand. Additionally, for a source 
operand specified as an unsigned immediate value, only a 1-byte immediate value may be specified. 


The shift control operand may be specified as an immediate operand, as a character(2) scalar, or as 
an unsigned binary(2) scalar. It provides an unsigned binary value indicating the number of bit posi- 
tions for which the left logical shift of the source bit string value is to be performed. A zero value 
specifies no shift. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Spacing addressing violation 

02 Boundary alignment violation 
03 Range 

06 Optimized addressability invalid 


x K K OK 
x Km K XK 
x KK K 


08 Argument/parameter 
01 Parameter reference violation X X X 
10 Damage encountered 
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Exception 


20 


22 


24 


2E 


32 


36 


04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Copy Bits with Left Logical Shift (CPYBTLLS) 


Operands 
1 2 3 Other 
X 
X 
X 
X 
X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X X 
X 
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Copy Bits with Right Arithmetic Shift (CPYBTRAS) 


Copy Bits with Right Arithmetic Shift (CPYBTRAS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
101B Receiver Source Shift Control 


Operand ?: Character variable or numeric variable scalar. 
Operand 2: Character scalar or numeric Scalar. 
Operand 3: Character(2) scalar (fixed length) or unsigned binary(2) scalar. 


Description: The instruction copies the bit string value of the source operand to the bit string defined 
by the receiver operand with a right arithmetic shift of the source bit string value under control of the 
shift control operand. 


The operation results in copying the shifted bit string value of the source to the bit string of the 
receiver while padding the receiver with bit values of 0 or 1 depending on the high order bit value of 
the source, and truncating bit values of the source as is appropriate for the specific operation. 


No indication is given of truncation of bit values from the shifted source value. This is true whether the 
values truncated are 0 or 1. 


The operation is performed such that the bit string of the source is considered a signed numeric binary 
value, with the value of the sign bit of the source conceptually extended on the left an unlimited 
number of bit string positions. A right arithmetic shift of the conceptual bit string value of the source is 
then performed according to the shift criteria specified in the shift control operand. No indication is 
given of truncation of bit values from the shifted conceptual source value. This is true whether the 
values truncated are 0 or 1. After the shift, the conceptual bit string value is then copied to the 
receiver, right aligned. 


Viewing the bit string value of the source and the bit string value copied to the receiver as signed 
numeric, the sign of the value copied to the receiver will be the same as the sign of the source. 


A right shift of one bit position is equivalent to dividing the signed numeric bit string value of the 
source by 2 with rounding downward, and assigning a signed numeric bit string equivalent to that 
result to the receiver. For example, if the signed numeric view of the source bit string is +9, shifting 
one bit position right yields +4. However if the signed numeric view of the source bit string is -9, 
shifting one bit position right yields -5. 


lf all the significant bits of the conceptual source bit string are shifted out of the field, the resulting 
conceptual bit string value will be all zero bits for positive numbers, and all one bits for negative 
numbers. 


The source and the receiver can be either character or numeric. Any numeric operands are inter- 
preted as logical character strings. Due to the operation being treated as a character string operation, 
the source operand may not be specified as a signed immediate operand. Additionally, for a source 
operand specified as an unsigned immediate value, only a 1-byte immediate value may be specified. 


The shift control operand may be specified as an immediate operand, as a character(2) scalar, or as a 
unsigned binary(2) scalar. It provides an unsigned binary value indicating the number of bit positions 
for which the right logical shift of the source bit string value is to be performed. A zero value specifies 
no shift. 


Exceptions 
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Copy Bits with Right Arithmetic Shift (CPYBTRAS) 


& 


Exception 1 2 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment violation 


03 Range 


~ KK OK 
x KK KK 
~ KK XK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation Xx X Xx 


10 Damage encountered 
04 System object damage state X 


44 Partial system object damage X 


1C Machine-dependent exception 


03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
03 Function check Xx 


22 Object access . 
02 Object destroyed X X X 
03 Object suspended X X X 


08 object compressed X 


24 Pointer specification 
01 Pointer does not exist xX xX X 
02 Pointer type invalid X X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 Scalar type invalid X X X 


36 Space management 


01 space extension/truncation X 
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Copy Bits with Right Logical Shift (CPYBTRLS) 


Copy Bits with Right Logical Shift (CPYBTRLS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
103F Receiver Source Shift control 


Operand ?: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 
Operand 3: Character(2) scalar (fixed length) or unsigned binary(2) scalar. 


Description: This instruction copies the bit string value of the source operand to the bit string defined 
by the receiver operand with a right logical shift of the source bit string value under control of the shift 
control operand. 


The operation results in copying the shifted bit string value of the source to the bit string of the 
receiver while padding the receiver with bit values of 0 and truncating bit values of the source as is 
appropriate for the specific operation. 


No indication is given of truncation of bit values from the shifted source value. This is true whether the 
values truncated are O or 1. 


The operation is performed such that the bit string of the source is considered to be extended on the 
left and right by an unlimited number of bit string positions of value 0. Additionally, a receiver bit 
string view (window) with the attributes of the receiver is considered to overlay this conceptual bit 
string value of the source starting at the leftmost bit position of the original source value. A right 
logical shift of the conceptual bit string value of the source is then performed relative to the receiver 
bit string view according to the shift criteria specified in the shift control operand. After the shift, the 
bit string value then contained within the receiver bit string view is copied to the receiver. 


The source and the receiver can be either character or numeric. Any numeric operands are inter- 
preted as logical character strings. Due to the operation being treated as a character string operation, 
the source operand may not be specified as a signed immediate operand. Additionally, for a source 
operand specified as an unsigned immediate value, only a 1-byte immediate value may be specified. 


The shift control operand may be specified as an immediate operand, as a character(2) scalar, or as a 
unsigned binary(2) scalar. It provides an unsigned binary value indicating the number of bit positions 
for which the right logical shift of the source bit string value is to be performed. A Zero value specifies 
no shift. 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 Spacing addressing violation X X Xx 

02 Boundary alignment violation X xX Xx 

03 Range X X X 

06 Optimized addressability invalid xX 4 xX 
08 Argument/parameter 

01 Parameter reference violation X X xX 
10 Damage encountered 
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Copy Bits with Right Logical Shift (CPYBTRLS) 


Operands 
Exception 1 2 3 Other 
04 System object damage state X 


44 Partial system object damage X 


ic Machine-dependent exception 


03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check Xx 
03 Function check Xx 


22 Object access 
02 Object destroyed X X X 
03 Object suspended X X X 


08 object compressed X 


24 Pointer specification 
01 Pointer does not exist X X X 
02 Pointer type invalid X X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 Scalar type invalid X X X 


36 Space management 


01 space extension/truncation X 
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Copy Bytes Left-Adjusted (CPYBLA) 


Copy Bytes Left-Adjusted (CPYBLA) 


Op Code (Hex) Operand 1 Operand 2 
10B2 Receiver Source 


Operand ?: Character variable scalar, numeric variable scalar, data-pointer-defined character scalar. 
or data-pointer-defined numeric scalar. 


Operand 2: Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- 
defined numeric scalar. 


Description: The logical string value of the source operand is copied to the logical string value of the 
receiver operand (no padding done). The operands can be either character or numeric. Any numeric 
Operands are interpreted as logical character strings. 


The length of the operation is equal to the length of the shorter of the two operands. The copying 
begins with the two operands left-adjusted and proceeds until the shorter operand has been copied. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for either operand is 
that no result is set. 


lf either operand is a character variable scalar, it may have a length as great as 16776191 bytes. 


Exceptions 

Operands 
Exception 1 2 Other 
06 Addressing 


01 Spacing addressing violation 
02 Boundary alignment 

03 Range 

04 External data object not found 


x KX KK K 
x KX KK XK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation »4 »« 


10 Damage encountered 
04 System object damage state X X X 
44 Partial system object damage X X X 


1C Machine-dependent exception 


03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
03 Function check X 


22 Object access 
01 Object not found X X 
02 Object destroyed X X 
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Exception 


24 


2E 


32 


36 


03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control! limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Copy Bytes Left-Adjusted (CPYBLA) 


Operands 
1 2 Other 
X X 
X 
X X 
X X 
xX 
X X 
X 
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Copy Bytes Left-Adjusted with Pad (CPYBLAP) 


Copy Bytes Left-Adjusted with Pad (CPYBLAP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
10B3 Receiver Source Pad 


Operand ?: Character variable scalar or numeric variable scalar, data-pointer-defined character 
scalar, or data-pointer-defined numeric scalar. 


Operand 2: Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- 
defined numeric scalar. 


Operand 3: Character scalar or numeric scalar. 


Description: The logical string value of the source operand is copied to the logical string value of the 
receiver operand (padded if needed). 


The operands can be either character or numeric. Any numeric operands are interpreted as logical 
character strings. 


The length of the operation is equal to the length of the receiver operand. If the source operand is 
shorter than the receiver operand, the source operand is copied to the leftmost bytes of the receiver 
operand, and each excess byte of the receiver operand is assigned the single byte value in the pad 
operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. If the source 
operand is longer than the receiver operand, the leftmost bytes of the source operand (equal in length 
to the receiver operand) are copied to the receiver operand. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that 
the bytes of the receiver are each set with the single byte value of the pad operand. The effect of 
specifying a null substring reference for the receiver is that no result is set. 


If either of the first two operands is a character variable scalar, it may have a length as great as 
16776191. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Spacing addressing violation 


X X 

02 Boundary alignment X xX xX 

03 Range X X X 

04 External data object not found X X 

06 Optimized addressability invalid Xx Xx »4 
08 Argument/parameter 

01 Parameter reference violation X X X 
10 Damage encountered 

04 System object damage state X X X X 

44 Partial system object damage X X X X 
1c Machine-dependent exception 
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Exception 


20 


22 


24 


2E 


32 


36 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Copy Bytes Left-Adjusted with Pad (CPYBLAP) 


Operands 
1 2 3 Other 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X 
X 
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Copy Bytes Overlap Left-Adjusted (CPYBOLA) 


Copy Bytes Overlap Left-Adjusted (CPYBOLA) 


Op Code (Hex) Operand 1 Operand 2 
10BA Receiver Source 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character variable scalar or numeric variable scalar. 


Description: The logical string value of the source operand is copied to the logical string value of the 
receiver operand (no padding done). The operands can be either character or numeric. Any numeric 
operands are interpreted as logical character strings. 


The length of the operation is equal to the length of the shorter of the two operands. The copying 
begins with the two operands left-adjusted and proceeds until the shorter operand has been copied. 
The excess bytes in the longer operand are not included in the operation. 


Predictable results occur even if two operands overlap because the source operand is, in effect, first 
copied to an intermediate result. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a nuil substring reference for either operand is 
that no result is set. 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment 


03 Range 


~ KK XK 
x KK XK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation D4 ».4 


10 Damage encountered 
04 System object damage state X X X 
44 Partial system object damage X X X 


1C Machine-dependent exception 


03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
03 Function check X 


22 Object access 
01 Object not found X X 
02 Object destroyed 
03 Object suspended X X 


~*~ 
~*~ 
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Exception 
08 object compressed 
24 Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


2E Resource control limit 


01 user profile storage limit exceeded 


32 Scalar specification 


01 Scalar type invalid 


36 Space management 


01 space extension/truncation 


Copy Bytes Overlap Left-Adjusted (CPYBOLA) 


Operands 

1 2 Other 
X 

X X 

X X 
X 

X X 
X 
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Copy Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) 


Copy Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
10BB Receiver Source Pad 


Operand ?: Character variable scalar or numeric variable scalar. 
Operand 2: Character variable scalar or numeric variable scalar. 
Operand 3: Character scalar or numeric scalar. 


Description: The logical string value of the source operand is copied to the logical string value of the 
receiver operand. 


The operands can be either character or numeric. Any numeric operands are interpreted as logical 
character strings. 


The length of the operation is equal to the length of the receiver operand. !f the source operand is 
shorter than the receiver operand, the source operand is copied to the leftmost bytes of the receiver 
Operand and each excess byte of the receiver operand is assigned the single byte value in the pad 
operand. !f the pad operand is more than 1 byte in length, only its leftmost byte is used. If the source 
operand is longer than the receiver operand, the leftmost bytes of the source operand (equal in length 
to the receiver operand) are copied to the receiver operand. 


Predictable results occur even if two operands overlap because the source operand is, in effect, first 
copied to an intermediate result. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
Specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that 
the bytes of the receiver are each set with the single byte value of the pad operand. The effect of 
specifying a null substring reference for the receiver is that no result is set. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment 


03 Range 


x KK RK 
x KK XK 
x KK K 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation X X xX 


10 Damage encountered 
04 System object damage state X X X X 
44 Partial system object damage X X X X 


1C Machine-dependent exception 


03 Machine storage limit exceeded X X 


20 Machine support 
02 Machine check 4 
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Copy Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) 


Exception 


22 


24 


2E 


36 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 


Other 
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Copy Bytes Repeatedly (CPYBREP) 


Op Code (Hex) Operand 1 Operand 2 
10BE Receiver Source 


Operand 7: Numeric variable scalar or character variable scalar (fixed-length). 
Operand 2: Numeric scalar or character scalar (fixed length). 


Description: The logical string value of the source operand is repeatedly copied to the receiver 
operand until the receiver is filled. The operands can be either character or numeric. Any numeric 
operands are interpreted as logical character strings. 


The operation begins with the two operands left-adjusted and continues until the receiver operand is 
completely filled. If the source operand is shorter than the receiver, it is repeatedly copied from left to 
right (all or in part) until the receiver operand is completely filled. If the source operand is longer than 
the receive operand, the leftmost bytes of the source operand (equal in length to the receiver operand) 
are copied to the receiver operand. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for either operand is 
that no result is set. 


If either operand is a character variable scalar, it may have a length as great as 16776191. 


Exceptions 


Exception 1 2 Other 
06 Addressing 
01 Spacing addressing violation 


X 
02 Boundary alignment X 
03 Range X 

X 


x KX KK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation X X 


10 Damage encountered 
04 System object damage state X X X 
44 Partial system object damage X X X 


1C Machine-dependent exception 
03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
03 Function check »4 


22 Object access 
01 Object not found X X 
02 Object destroyed xX 
03 Object suspended X X 


~< 
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Exception 
08 object compressed 
24 Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


2E Resource control limit 


01 user profile storage limit exceeded 


36 Space management 


01 space extension/truncation 


Copy Bytes Repeatedly (CPYBREP) 


Operands 

1 2 Other 
X 

Xx X 

X xX 
Xx 
X 
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Copy Bytes Right-Adjusted (CPYBRA) 


Copy Bytes Right-Adjusted (CPYBRA) 


Op Code (Hex) Operand 1 Operand 2 
10B6 Receiver Source 


Operand 1: Character variable scalar, numeric variable scalar, data-pointer-defined character scalar. 
or data-pointer-defined numeric scalar. 


Operand 2: Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- 
defined numeric scalar. 


Description: The logical string value of the source operand is copied to the logical string vaiue of the 
receiver operand (no padding done). The operands can be either character or numeric. Any numeric 
operands are interpreted as logical character strings. 


The length of the operation is equal to the length of the shorter of the two operands. The rightmost 
bytes (equal to the length of the shorter of the two operands) of the source operand are copied to the 
rightmost bytes of the receiver operand. The excess bytes in the longer operand are not included in 
the operation. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for either operand is 
that no result is set. 


Exceptions 

Operands 
Exception 1 2 Other 
06 Addressing 


01 Spacing addressing violation 

02 Boundary alignment 

03 Range 

04 External data object not found 
06 Optimized addressability invalid 


x KK K K 
x K KK RK 


08 Argument/parameter 


01 Parameter reference violation xX xX 


10 Damage encountered 
04 System object damage state X X X 
44 Partial system object damage X X X 


1c Machine-dependent exception 


03 Machine storage limit exceeded Xx 


20 Machine support 
02 Machine check X 
03 Function check Xx 


22 Object access 
01 Object not found X X 
02 Object destroyed X X 
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Exception 


24 


2E 


32 


36 


03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Copy Bytes Right-Adjusted (CPYBRA) 


Operands 
1 2 Other 
Xx X 
X 
X X 
X X 
X 
X X 
X 
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Copy Bytes Right-Adjusted with Pad (CPYBRAP) 


Copy Bytes Right-Adjusted with Pad (CPYBRAP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
10B7 Receiver Source Pad 


Operand f: Character variable scalar, numeric variable scalar, data-pointer-defined character scalar, 
or data-pointer-defined numeric scalar. 


Operand 2: Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- 
defined numeric scalar. 


Operand 3: Character scalar or numeric scalar. 


Description: The logical string value of the source operand is copied to the logical string value of the 
receiver operand (padded if needed). The operands can be either character or numeric. Any numeric 
Operands are interpreted as logical character strings. 


The length of the operation is equal to the length of the receiver operand. If the source operand is 
shorter than the receiver operand, the source operand is copied to the rightmost bytes of receiver 
operand, and each excess byte is assigned the single byte value in the pad operand. If the pad 
operand is more than 1 byte in length, only its leftmost byte is used. If the source operand is longer 
than the receiver operand, the rightmost bytes of the source operand (equal in length to the receiver 
operand) are copied to the receiver operand. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that 
the bytes of the receiver are each set with the single byte value of the pad operand. The effect of 
specifying a null substring reference for the receiver is that no result is set. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Spacing addressing violation 
02 Boundary alignment 

03 Range 

04 External data object not found 


x KK KK 
x K KK OK 
x< 


06 Optimized addressability invalid X 
08 Argument/parameter 
01 Parameter reference violation x X X 
10 Damage encountered 
04 System object damage state X X X Xx 
44 Partial system object damage Xx X X X 
1C Machine-dependent exception 
03 Machine storage limit exceeded xX 
20 Machine support 
02 Machine check X 
03 Function check X 


Chapter 2. Computation and Branching Instructions 2-122 


Exception 


22 


24 


2E 


32 


36 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Copy Bytes Right-Adjusted with Pad (CPYBRAP) 


Operands 
1 2 3 Other 


X X X 
X X X 

X 
X X Xx 
X Xx Xx 

X 
X X 

X 
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Copy Bytes to Bits Arithmetic (CPYBBTA) 


Copy Bytes to Bits Arithmetic (CPYBBTA) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
104C Receiver Offset Length Source 


Operand /: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 2: Signed binary immediate or unsigned binary immediate. 
Operand 3: Signed binary immediate or unsigned binary immediate. 
Operand 4: Character variable scalar (fixed length) or numeric variable scalar. 


Description: This instruction copies a byte string from the source operand to a bit string in the 
receiver operand. 


The source operand is interpreted as a signed binary value and may be sign extended or truncated on 
the left to fit into the bit string in the receiver operand. No indication is given when truncation occurs. 


The location of the bit string in the receiver operand is specified by the offset operand. The value of 
the offset operand specifies the bit offset from the start of the receiver operand to the start of the bit 
string. Thus, an offset operand value of 0 specifies that the bit string starts at the leftmost bit position 
of the receiver operand. 


The length of the bit string in the receiver operand is specified by the length operand. The value of the 
length operand specifies the length of the bit string in bits. 


Limitations: The following are limits that apply to the functions performed by this instruction. 

lf the source operand and the bit string in the receiver operand overlap, the results are unpredictable. 
A source operand longer than 4 bytes may not be specified. 

If the offset operand is signed binary immediate, a negative value may not be specified. 

A length operand with a value less than 1 or greater than 32 may not be specified. 


The bit string specified by the offset operand and the length operand may not extend outside the 
receiver operand. 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Spacing addressing violation X X 
02 Boundary alignment violation X X . 
03 Range Xx X 
06 Optimized addressability invalid Xx X 
08 Argument/parameter 
01 Parameter reference violation X X 
10 Damage encountered 
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Exception 


1C 


20 


22 


24 


2E 


36 


04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Copy Bytes to Bits Arithmetic (CPYBBTA) 


Operands 

1 2 3 4 Other 
X 
X 
Xx 
X 
X 

X X 

X X 
X 

X X 

X X 
X 
X 
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Copy Bytes to Bits Logical (CPYBBTL) 


Copy Bytes to Bits Logical (CPYBBTL) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
103C Receiver Offset Length Source 


Operand 7: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 2: Signed binary immediate or unsigned binary immediate. 
Operand 3: Signed binary immediate or unsigned binary immediate. 
Operand 4: Character variable scalar (fixed length) or numeric variable scalar. 


Description: This instruction copies a byte string from the source operand to a bit string in the 
receiver operand. 


The source operand is interpreted as an unsigned binary value and may be padded on the left with 0’s 
or truncated on the left to fit into the bit string in the receiver operand. No indication is given when 
truncation occurs. 


The location of the bit string in the receiver operand is specified by the offset operand. The value of 
the offset operand specifies the bit offset from the start of the receiver operand to the start of the bit 
string. Thus, an offset operand value of 0 specifies that the bit string starts at the leftmost bit position 
of the receiver operand. 


The length of the bit string in the receiver operand is specified by the length operand. The value of the 
length operand specifies the length of the bit string in bits. 


Limitations: The following are limits that apply to the functions performed by this instruction. 

If the source operand and the bit string in the receiver operand overlap, the results are unpredictable. 
A source operand longer than 4 bytes may not be specified. 

If the offset operand is signed binary immediate, a negative value may not be specified. 

A length operand with a value less than 1 or greater than 32 may not be specified. 


The bit string specified by the offset operand and the length operand may not extend outside the 
receiver operand. 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Spacing addressing violation X xX 
02 Boundary alignment violation X X 
03 Range X X 
06 Optimized addressability invalid X X 
08 Argument/parameter 
01 Parameter reference violation X y,§ 
10 Damage encountered 
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Exception 


20 


22 


24 


2E 


36 


04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncatian 


Copy Bytes to Bits Logical (CPYBBTL) 


Operands 

1 2 3 4 Other 
Xx 
x 
X 
X 
X 

X X 

X X 
X 

X X 

X X 
X 
X 
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SS 


Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 


Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
1053 Receiver Source Pad 


Operand 1: Data-pointer-defined character scalar. 
Operand 2: Data-pointer-defined character scalar. 
Operand 3: Character(3) scalar or null. 


Description: The extended character string value of the source operand is copied to the receiver 
operand. 


The operation is performed at the length of the receiver operand. If the source operand is shorter than 
the receiver, the source operand is copied to the leftmost bytes of the receiver and the excess bytes of 
the receiver are assigned the appropriate value from the pad operand. 


The pad operand, operand 3, is three bytes in length and has the following format: 


e Pad operand Char(3) 
— Single byte pad value Char(1) 
— Double byte pad vaiue Char(2) 


lf the pad operand is more than three bytes in length, only its leftmost three bytes are used. Specifying 
a null pad operand results in default pad values of hex 40, for single byte, and hex 4040, for double 


byte, being used. The single byte pad value and the first byte of the double byte pad value cannot be 
either a shift out control character (SO = hex OE) value or a shift in control character (SI = hex OF) 
value. Specification of such an invalid value results in the signaling of the scalar value invalid (hex 


3203) exception. 


Operands 1 and 2 must be specified as Data Pointers which define either a simple (single byte) char- 
acter data field or one of the extended (double byte) character data fields. 


Support for usage of a Data Pointer defining an extended character scalar value is limited to this 
instruction. Usage of such a data pointer defined value on any other instruction is not supported and 
results in the signaling of the scalar type invalid (nex 3201) exception. 


For more information on support for extended character data fields, refer to the Set Data Pointer Attri- 
butes, Materialize Pointer, and Create Cursor instructions. 


Four data types are supported for data pointer definition of extended (double byte) character fields, 
OPEN, EITHER, ONLYNS and ONLYS. Except for ONLYNS, the double byte character data must be sur- 
rounded by a shift out control character (SO hex OE) and a shift in control character (SI = hex OF). 


e The ONLYNS field only contains double byte data with no SO, SI delimiters surrounding it. 
e The ONLYS field can only contain double byte character data within a SO..SI pair. 


e The EITHER field can consist of double byte character or single byte character data but only one 
type at a time. If double byte character data is present it must be surrounded by an SO .. SI pair. 


e The OPEN field can consist of a mixture of double byte character and single byte character data. If 
double byte character data is present it must be surrounded by an SO .. SI pair. 


Specifying an extended character value which violates the above restrictions results in the signaling of 
the invalid extended character data (hex 0C12) exception. 
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Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 


The valid copy operations which can be specified on this instruction are the following: 
Op 1 


Onlyns Onlys Open Either 


0 Onlyns 

p Onlys 
Open 

2 Either 


Figure 2-5. Valid copy operations for CPYECLAP 


Specifying a copy operation other than the valid operations defined above results in the signaling of 
the invalid extended character operation (hex 0C13) exception. 


When the copy operation is for a source of type ONLYNS (no SO/SI delimiters) being copied to a 
receiver which is not ONLYNS, SO and SI delimiters are implicitly added around the source value as 
part of the copy operation. 


When the source value is longer than can be contained in the receiver, truncation is necessary and the 
following truncation rules apply: 


1. Truncation is on the right (like simple character copy operations). 


2. When the string to be truncated is a single byte character string, or an extended character string 
when the receiver is ONLYNS, bytes beyond those that fit into the receiver are truncated with no 
further processing needed. 


3. When the string to be truncated is an extended character string and the receiver is not ONLYNS, 
the bytes that fall at the end of the receiver are truncated as follows: 


a. When the last byte that would fit in the receiver is the first byte of an extended character, that 
byte is truncated and replaced with an S! character. 


b. When the last byte that would fit in the receiver is the second byte of an extended character, 
both bytes of that extended character are truncated and replaced with a SI character followed 
by a single byte pad value. This type of truncation can only occur when converting to an OPEN 
field. 


When the source value is shorter than that which can be contained in the receiver, padding is neces- 
sary. One of three types of padding is performed: 


1. Double byte (DB) - the source value is padded on the right with double byte pad values out to the 
length of the receiver. 


2. Double byte concatenated with a SI value (DB]|SI) - the source double byte value is padded on the 
right with double byte pad values out to the second to last byte of the receiver and an Si delimiter 
is placed in the last byte of the receiver. 


3. Single byte (SB) - the source value is padded on the right with single byte pad values out to the 
length of the receiver. 
The type of padding performed is determined by the type of operands involved in the operation: 
1. If the receiver is ONLYNS, DB padding is performed. 
2. If the receiver is ONLYS, DB]|SI padding will be performed. 


3. If the receiver is EITHER and the source contained a double byte value, DB||S! padding is per- 
formed. 


4. If the receiver is EITHER and the source contained a single byte value, SB padding is performed. 
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5. If the receiver is OPEN, SB padding is performed. 


Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 


The above padding rules cover all the operand combinations which are allowed on the instruction. A 
complete understanding of the operand combinations allowed (prior diagram), and the values which 
can be contained in the different operand types is necessary to appreciate that these rules do cover all 
the valid combinations. 


Exceptions 


Exception 


06 


08 


oc 


10 


20 


22 


24 


2E 


32 


Addressing 

01 Spacing addressing violation 
02 Boundary alignment 

03 Range 

04 External data object not found 


06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Computation 
12 Invalid extended character data 


13 Invalid extended character operation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


01 Scalar value invalid 


Operands 


1 2 3 Other 


x KX KK KM 
x KX KK KM 
x 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X 
X 
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Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 


Operands 
Exception 1 2 3 Other 


36 Space management ) ) 
01 space extension/truncation x 


eyes 
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Copy Hex Digit Numeric to Numeric (CPYHEXNN) 


Copy Hex Digit Numeric to Numeric (CPYHEXNN) 


Op Code (Hex) Operand 1 Operand 2 
1092 Receiver Source 


Operand 1: Numeric variable scalar or character variable scalar (fixed-length). 
Operand 2: Numeric scalar or character scalar (fixed-length). 


Description: The numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by the 


source operand is copied to the numeric hex digit value (rightmost 4 bits) of the leftmost byte referred 
to by the receiver operand. The operands can be either character strings or numeric. Any numeric 


operands are interpreted as logical character strings. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 Spacing addressing violation X X 

02 Boundary alignment X X 

03 Range X X 

06 Optimized addressability invalid X X 
08 Argument/parameter 

01 Parameter reference violation X X 
10 Damage encountered 

04 System object damage state X X X 

44 Partial system object damage X X X 
ic Machine-dependent exception 

03 Machine storage limit exceeded X 
20 Machine support 

02 Machine check X 

03 Function check X 
22 Object access 

01 Object not found | X X 

02 Object destroyed X X 

03 Object suspended X X 

08 object compressed X 
24 Pointer specification 

01 Pointer does not exist X X 

02 Pointer type invalid X X 
2E Resource control limit 

01 user profile storage limit exceeded X 
36 Space management 
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Copy Hex Digit Numeric to Numeric (CPYHEXNN) 


Operands 
Exception 1 2 Other 
01 space extension/truncation X ) 
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Copy Hex Digit Numeric to Zone (CPYHEXNZ) 


Copy Hex Digit Numeric to Zone (CPYHEXNZ) 


Op Code (Hex) Operand 1 Operand 2 
1096 Receiver Source 


Operand 7: Numeric variable scalar or character variable scalar (fixed-length). 
Operand 2: Numeric scalar or character scalar (fixed-length). 


Description: The numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by the 


source operand is copied to the numeric hex digit value (rightmost 4 bits) of the leftmost byte referred 
to by the receiver operand. The operands can be either character strings or numeric. Any numeric 


operands are interpreted as Jogical character strings. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 Spacing addressing violation X X 

02 Boundary alignment X X 

03 Range X X 

06 Optimized addressability invalid X X 
08 Argument/parameter 

01 Parameter reference violation X X 
10 Damage encountered 

04 System object damage state X X X 

44 Partial system object damage X X X 
ic Machine-dependent exception 

03 Machine storage limit exceeded X 
20 Machine support 

02 Machine check X 

03 Function check X 
22 Object access 

01 Object not found X X 

02 Object destroyed X X 

03 Object suspended X X 

08 object compressed X 
24 Pointer specification 

01 Pointer does not exist X X 

02 Pointer type invalid X X 
2E Resource control limit 

01 user profile storage limit exceeded X 
36 Space management 


Chapter 2. Computation and Branching Instructions 


2-134 


Copy Hex Digit Numeric to Zone (CPYHEXNZ) 


Operands 
Exception 1 2 Other 
01 space extension/truncation X > 


Chapter 2. Computation and Branching Instructions 2-135 


Copy Hex Digit Zone To Numeric (CPYHEXZN) 


Copy Hex Digit Zone To Numeric (CPYHEXZN) 


Op Code (Hex) Operand 1 Operand 2 
109A Receiver Source 


Operand 7: Numeric variable scalar or character variable scalar (fixed-length). 
Operand 2: Numeric scalar or character scalar (fixed-length). 


Description: The zone hex digit value (leftmost 4 bits) of the leftmost byte referred to by the source 
operand is copied to the numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by 
the receiver operand. 


The operands can be either character strings or numeric. Any numeric operands are interpreted as 
logical character strings. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 Spacing addressing violation X X 

02 Boundary alignment X X 

03 Range X xX 

06 Optimized addressability invalid X X 
08 Argument/parameter 

01 Parameter reference violation X X 
10 Damage encountered 

04 System object damage state X X X 

44 Partial system object damage X X X 
1C Machine-dependent exception 

03 Machine storage limit exceeded X 
20 Machine support 

02 Machine check X 

03 Function check X 
22 Object access 

01 Object not found X X 

02 Object destroyed X X 

03 Object suspended X X 

08 object compressed Xx 
24 Pointer specification 

01 Pointer does not exist xX X 

02 Pointer type invalid X X 
2E Resource control limit 

01 user profile storage limit exceeded X 
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Copy Hex Digit Zone To Numeric (CPYHEXZN) 


Operands 
Exception 1 2 Other 


36 Space management j 
01 space extension/truncation X 
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Copy Hex Digit Zone To Zone (CPYHEXZZ) 


Copy Hex Digit Zone To Zone (CPYHEXZZ) 


Op Code (Hex) Operand 1 Operand 2 


109E 


Receiver Source 


Operand 1: Numeric variable scalar or character variable scalar (fixed-length). 


Operand 2: Numeric scalar or character scalar (fixed-length). 


Description: The zone hex digit value (leftmost 4 bits) of the leftmost byte referred to by the source 
operand is copied to the zone hex digit value (leftmost 4 bits) of the leftmost byte referred to by the 
receiver operand. 


The operands can be either character strings or numeric. Any numeric operands are interpreted as 
logical character strings. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 Spacing addressing violation X X 

02 Boundary alignment X X 

03 Range X X 

06 Optimized addressability invalid X X 
08 Argument/parameter 

01 Parameter reference violation X X 
10 Damage encountered 

04 System object damage state X X X 

44 Partial system object damage X X X 
1C Machine-dependent exception 

03 Machine storage limit exceeded X 
20 Machine support 

02 Machine check X 

03 Function check X 
22 Object access 

01 Object not found X X 

02 Object destroyed X X 

03 Object suspended X X 

08 abject compressed X 
24 Pointer specification 

01 Pointer does not exist X X 

02 Pointer type invalid X X 
2E Resource control limit 

01 user profile storage limit exceeded X 
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Copy Hex Digit Zone To Zone (CPYHEXZZ) 


Operands 
Exception 1 2 Other 


36 Space management 
01 space extension/truncation X 
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Copy Numeric Value (CPYNV) 


Copy Numeric Value (CPYNV) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
CPYNV Receiver Source 

1042 

CPYNVR Receiver Source 

1242 

CPYNVB Branch options Receiver Source Branch targets 
1C42 

CPYNVBR Branch options Receiver Source Branch targets 
1E42 

CPYNVI Indicator options Receiver Source Indicator targets 
1842 

CPYNVIR Indicator options Receiver Source Indicator targets 
1A42 


Operand 1: Numeric variable scalar or data-pointer-defined numeric scalar. 
Operand 2: Numeric scalar or data pointer-defined-numeric scalar. 


Operand 3-6: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
LBCPYNV ( 
var receiver : any numeric type; 
var receiver_attributes : aggregate; 
var source : any numeric type; 


var source attributes : aggregate; 


Description: The numeric value of the source operand is copied to the numeric receiver operand. 


Both operands must be numeric. If necessary, the source operand is converted to the same type as 
the receiver operand before being copied to the receiver operand. The source value is adjusted to the 
length of the receiver operand, aligned at the assumed decimal point of the receiver operand, or both 
before being copied to it. If significant digits are truncated on the !eft end of the source value, a size 
(hex OCOA) exception is signaled. When the receiver is binary, this size (hex OCOA) exception may be 
suppressed by using the suppress binary size exception program attribute on the Create Program 
(CRTPG) instruction. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled or if the size (hex 
OCOA) exception is suppressed, the binary value contains the correct truncated result only if the 
decimal value contains 15 or fewer significant nonfractional digits. 
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Copy Numeric Value (CPYNV) 


Conversions between floating-point integers and integer formats (binary or decimal with no fractional 
digits) is exact, except when an exception is signaled. 


An invalid floating-point conversion (hex OCOC) exception is signaled when an attempt is made to aA 
convert from floating-point to binary or decimal and the result would represent infinity or NaN, or 
nonzero digits would be truncated from the left end of the resultant value. 


For the optional round form of the instruction, a floating-point receiver operand is invalid. 


For a fixed-point operation, if significant digits are truncated from the left end of the source value, a 
size (hex OCOQA) exception is signaled. When the receiver is binary, this size (hex OCOA) exception may 
be suppressed by using the suppress binary size exception program attribute on the Create Program 
(CRTPG) instruction. 


For a floating-point receiver, if the exponent of the resultant value is too large or too small to be 
represented in the receiver field, the floating-point overflow (hex O0C06) and floating-point underflow 
(hex 0C0O7) exceptions are signaled, respectively. 


Resultant Conditions 
e Positive-The algebraic value of the numeric scalar receiver operand is positive. 
e Negative-The algebraic value of the numeric scalar receiver operand is negative. 
e Zero-The algebraic value of the numeric scalar receiver operand is Zero. 


e Unordered-The value assigned a floating-point receiver operand is NaN. | 


Exceptions 
Operands -) 
Exception 1 2 Other 
06 Addressing 
01 Spacing addressing violation 
02 Boundary alignment 
03 Range 


04 External data object not found 


x KKK XK 
x KK KK 


06 Optimized addressability invalid 


08 Argument/parameter 


>< 
~< 


01 Parameter reference violation 


0c Computation 
02 Decimal data X 
06 Floating-point overflow 
07 Floating-point underlow 
09 Floating-point invalid operand 
0A Size 


OC Invalid floatin-point conversion 


x KK KK KM 


0A Floating-point inexact result 


10 Damage encountered 
04 System object damage state X X Xx ) 
44 Partial system object damage X X X 
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Exception 


1C 


20 


22 


24 


2C 


2E 


32 


36 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource contro! limit 


01 user profile storage limit exceeded 


Scalar specification 


01 Scalar type invalid 


Space management 


01 space extension/truncation 


Copy Numeric Value (CPYNV) 


Operands 
1 2 Other 


Xx 
X 
X 

X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X X 
X 
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Decompress Data (DCPDATA) 


Decompress Data (DCPDATA) 


Op Code (Hex) Operand 1 


1051 Decompress Data 
template 


Operand ?: Space pointer. 


ILE access 


DCPDATA ( 
decompress data template : space pointer 
) 


Description: The instruction decompresses user data. Operand 1 identifies a template which identi- 
fies the data to be decompressed. The template also identifies the result space to receive the decom- 
pressed data. 


The Decompress Data template must be aligned on a 16-byte boundary. The format is as follows: 


e Reserved (binary 0) Char(4) 

e Result area length Bin(4) 

e Actual result length | Bin(4)* 

¢ Reserved (binary 0) Char(20) 

e Source space pointer Space pointer 
e Result space pointer Space pointer 


Note: The input value associated with template entries annotated with an asterisk (*) are ignored by 
the instruction; these fields are updated by the instruction to return information about instruction 
execution. 


The data at the location specified by the source space pointer is decompressed and stored at the 
location specified by the result space pointer. The actual result length is set to the number of bytes in 
the decompressed result. The Source data is not modified. 


The result area length field value must be greater than zero. The length of the source data is not 
supplied in the template because this length is contained within the compressed data. 


If the decompressed result data will not fit in the result area (as specified by the resu/t area length), the 
decompression is stopped and only as many decompressed bytes as will fit in the result area are 
stored. The actual result length is always set to the full length of the result, which may be larger than 
the result area length. 


The compressed data (previously compressed with CPRDATA) contains a signature which is checked 
by DCPDATA. The signature indicates which compression algorithm was used to compress the data. 
If the signature is invalid, an invalid compressed data (hex 0C14) exception is signaled. It is possible 
that the signature appears valid even though the compressed data has been corrupted. In almost all 
cases, the DCPDATA instruction will signal the invalid compressed data (hex 0C14) exception. Data 
corruption will not be detected only in the case when the decompression algorithm applied to the cor- 
rupted data produces the correct number of decompressed bytes. 


It is not possible to corrupt the compressed data in such a way that the DCPDATA instruction would fail 
(that is, function check) or fail to terminate (that is, loop). 
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Decompress Data (DCPDATA) 


Authorization Required 


« None 


Lock Enforcement 


« None 
Exceptions 
Operands 

Exception 1 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X 

03 range X 

06 optimized addressability invalid X 
08 Argument/Parameter 

01 Parameter reference violation X 
0c Computation 

14 invalid compressed data X 
10 Damage encountered 

44 partial system object damage X X 
1C Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check X 

03 function check X 
22 Object access 

02 object destroyed X X 

03 object suspended X X 

08 object compressed X 
24 Pointer specification 

01 pointer does not exist X X 

02 pointer type invalid X X 

03 pointer addressing invalid object X X 
2E Resource control limit 

01 user profile storage limit exceeded X 
36 Space management 

01 space extension/truncation X X 
38 Template specification 

01 template value invalid X 


Chapter 2. Computation and Branching Instructions 2-144 


Decompress Data (DCPDATA) 


Operands 
Exception 1 Other 
44 Domain 


01 object domain error X -, 
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Divide (DIV) 


Divide (DIV) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-7 ] 
DIV Quotient Dividend Divisor 

104F 

DIVR Quotient Dividend Divisor 

124F 

DIVI Indicator Quotient Dividend Divisor Indicator targets 
184F options 

DIVIR Indicator Quotient Dividend Divisor Indicator targets 
1A4F options 

DIVB Branch options Quotient Dividend Divisor Branch targets 
1C4F 

DIVBR Branch options Quotient Dividend Divisor Branch targets 
1E4F 


Operand 1: Numeric variable scalar. 
Operand 2: Numeric scalar. 
Operand 3: Numeric scalar. 


Operand 47. 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
Divs Quotient/Dividend Divisor 

114F 

DIVSR Quotient/Dividend Divisor 

134F 

DIVIS Indicator options Quotient/Dividend Divisor Indicator targets 
194F 

DIVISR Indicator options Quotient/Dividend Divisor Indicator targets 
1B4F 

DIVBS Branch options Quotient/Dividend Divisor Branch targets 
1D4F 

DIVBSR Branch options Quotient/Dividend Divisor Branch targets 
1F4F 


Operand ?: Numeric variable scalar. 
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Operand 2: Numeric scalar. 


Operand 3-6: 
¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 
Description: The Quotient is the result of dividing the Dividend by the Divisor. 
Operands can have floating-point, packed or zoned decimal, signed or unsigned binary type. 
source operands are the Dividend and Divisor. The receiver operand is the Quotient. 


If operands are not of the same type, source operands are converted according to the following rules: 


1. If any one of the operands has floating point type, source operands are converted to floating point 
type. 


2. Otherwise, if any one of the operands has zoned or packed decimal type, source operands are 
converted to packed decimal. 


3. Otherwise, the binary operands are converted to a like type. Note: unsigned binary(2) scalars are 
logically treated as signed binary(4) scalars. 


source operands are divided according to their type. Floating point operands are divided using 
floating point division. Packed decimal operands are divided using packed decimal division. Unsigned 
binary division is used with unsigned source operands. Signed binary operands are divided using 
two’s complement binary division. 


Better performance can be obtained if all operands have the same type. Signed and unsigned binary J 
division execute faster than either packed decimal or floating point division. 


Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. 


If the divisor has a numeric value of zero, a zero divide (nex OCOB) or floating-point zero divide (hex 
OCOE) exception is signaled respectively for fixed-point versus floating-point operations. If the dividend 
has a value of zero, the result of the division is a zero quotient value. 


If the divisor has a numeric value of 0, a zero divide (hex OCOB) exception is signaled. If the dividend 
has a value of O, the result of the division is a zero value quotient. 


For a decimal operation, the precision of the result of the divide operation is determined by the 
number of fractional digit positions specified for the quotient. In other words, the divide operation will 
be performed so as to calculate a resultant quotient of the same precision as that specified for the 
quotient operand. If necessary, internal alignment of the assumed decimal point for the dividend and 
divisor operands is performed to ensure the correct precision for the resultant quotient value. These 
internal alignments are not subject to detection of the decimal point alignment exception. An internal 
quotient value will be calculated for any combination of decimal attributes which may be specified for 
the instruction’s operands. However, the assignment of the result to the quotient operand is subject to 
detection of the size (hex OCOA) exception thereby limiting the assignment to, at most, the rightmost 31 
digits of the calculated result. 


Floating-point division uses exponent subtraction and significand division. 


If the dividend operand is shorter than the divisor operand, it is logically adjusted to the length of the ; 
divisor operand. 
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For fixed-point computations and for the significand division of a floating-point computation, the division 
operation is performed according to the rules of algebra. Unsigned binary is treated as a positive 
number for the algebra. 


For a floating-point computation, the operation is performed as if to infinite precision. 


The result of the operation is copied into the quotient operand. |f this operand is not the same type as 
that used in performing the operation, the resultant value is converted to its type. If necessary, the 
resultant value is adjusted to the length of the quotient operand, aligned at the assumed decimal point 
of the quotient operand, or both before being copied to it. If significant digits are truncated on the left 
end of the resultant value, a size (hex OCOA) exception is signaled. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 


For the optional round form of the instruction, specification of a floating-point receiver operand is 
invalid. 


For fixed-point operations in programs that request to be notified of size (hex OCOA) exceptions, if 
nonzero digits are truncated from the left end of the resultant value, a size (hex OCOA) exception is 
signaled. 


For floating-point operations that involve a fixed-point receiver field, if nonzero digits would be trun- 
cated from the left end of the resultant vaiue, an invalid floating-point conversion (hex OCOC) exception 
is signaled. 


For a floating-point quotient operand, if the exponent of the resultant value is either too large or too 
small to be represented in the quotient field, the floating-point overflow (hex OCQ6) and floating-point 
underflow (hex 0C07) exceptions are signaled, respectively. 
Resultant Conditions 

e Positive-The algebraic value of the numeric scalar quotient is positive. 

¢ Negative-The algebraic value of the numeric scalar quotient is negative. 

« Zero-The algebraic value of the numeric scalar quotient is or zero. 


e Unordered-The value assigned a floating-point quotient operand is NaN. 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 Spacing addressing violation X X xX 

02 Boundary alignment Xx Xx Xx 

03 Range xX Xx xX 

06 Optimized addressability invalid X X x 
08 Argument/parameter 

01 Parameter reference violation 4 X X 
0C Computation 

02 Decimal data X X 

06 Floating-point overflow X 
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Exception 


10 


20 


22 


24 


2C 


2E 


36 


07 Floating-point underlow 

09 Floating-point invalid operand 
0A Size 

OB Zero divide 

OC Invalid floatin-point conversion 
0D Floating-point inexact result 


OE Floating-point divide by zero 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Divide (DIV) 


Operands 
1 2 3 Other 
X 
X X X 
X 
X 
X 
X 


X 
X 
X 
X X X 
X X Xx 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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Divide with Remainder (DIVREM) 


Op Code Extender Operand 1 Operand 2 Operand 3 Operand 4 Operand [5-7] 
(Hex) 

DIVREM Quotient Dividend Divisor Remainder 

1074 

DIVREMR Quotient Dividend Divisor Remainder 

1274 

DIVREMI Indicator Quotient Dividend Divisor Remainder Indicator 
1874 options targets 
DIVREMIR Indicator Quotient Dividend Divisor Remainder Indicator 
1A74 options targets 
DIVREMB Branch Quotient Dividend Divisor Remainder Branch 
1074 options targets 
DIVREMBR Branch Quotient Dividend Divisor Remainder Branch 
1E74 options targets 


Operand 7: Numeric variable scalar. 
Operand 2: Numeric scalar. 
Operand 3: Numeric scalar. 
Operand 4: Numeric variable scalar. 


Operand 5-7: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-6] 
DIVREMS Quotient/Dividend Divisor Remainder 

1174 

DIVREMSR Quotient/Dividend Divisor Remainder 

1374 

DIVREMIS Indicator Quotient/Dividend Divisor Remainder Indicator targets 
1974 options 

DIVREMISR Indicator Quotient/Dividend Divisor Remainder Indicator targets 
1B74 options 

DIVREMBS Branch options Quotient/Dividend Divisor Remainder Branch targets 
1074 

DIVREMBSR Branch options Quotient/Dividend Divisor Remainder Branch targets 
1F74 


Operand 7: Numeric variable scalar. 
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Operand 2: Numeric scalar. 
Operand 3: Numeric variable scalar. 


Operand 4-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The Quotient is the result of dividing the Dividend by the Divisor. The Remainder is the 
Dividend minus the product of the Divisor and Quotient. 


Operands can have packed or zoned decimal, signed or unsigned binary type. 


Source operands are the Dividend and Divisor. The receiver operands are the Quotient and 
Remainder. 


If operands are not of the same type, source operands are converted according to the following rules: 


1. If any one of the operands has zoned or packed decimal type, source operands are converted to 
packed decimal. 


2. Otherwise, the binary operands are converted to a like type. Note: unsigned binary(2) scalars are 
logically treated as signed binary(4) scalars. 


Source operands are divided according to their type. Packed decimal operands are divided using 
packed decimal division. Unsigned binary division is used with unsigned source operands. Signed 
binary operands are divided using two’s complement binary division. 


Better performance can be obtained if all operands have the same type. Signed and unsigned binary 
division execute faster than packed decimal division. 


Floating-point is not supported for this instruction. 


lf the divisor operand has a numeric value of 0, a zero divide (hex OCOB) exception is signaled. If the 
dividend operand has a value of 0, the result of the division is a zero value quotient and remainder. 


For a decimal operation, the precision of the result of the divide operation is determined by the 
number of fractional digit positions specified for the quotient. In other words, the divide operation will 
be performed so as to calculate a resultant quotient of the same precision as that specified for the 
quotient operand. If necessary, internal alignment of the assumed decimal point for the dividend and 
divisor operands is performed to ensure the correct precision for the resultant quotient value. These 
internal alignments are not subject to detection of the decimal point alignment exception. An internal 
quotient value will be calculated for any combination of decimal attributes which may be specified for 
the instruction’s operands. However, the assignment of the result to the quotient operand is subject to 
detection of the size exception thereby limiting the assignment to, at most, the rightmost 31 digits of 
the calculated result. 


If the dividend operand is shorter than the divisor operand, it is logically adjusted to the length of the 
divisor operand. 


The division operation is performed according to the rules of algebra. Unsigned binary is treated as a 
positive number for the algebra. The quotient result of the operation is copied into the quotient 
operand. If this operand is not the same type as that used in performing the operation, the resultant 
value is converted to its type. If necessary, the resultant value is adjusted to the length of the quotient 
operand, aligned at the assumed decimal point of the quotient operand, or both before being copied to 
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it. If significant digits are truncated on the left end of the resultant value, a size (hex OCOA) exception 
is signaled. 


After the quotient numeric value has been determined, the numeric value of the remainder operand is 
calculated as follows: 


Remainder = Dividend - (Quotient*Divisor) 


If the optional round form of this instruction is being used, the rounding applies to the quotient but not 
the remainder. The quotient value used to calculate the remainder is the resultant value of the divi- 
sion. The resultant value of the calculation is copied into the remainder operand. The sign of the 
remainder is the same as that of the dividend operand unless the remainder has a value of 0, in which 
case its sign is positive. If the remainder operand is not the same type as that used in performing the 
operation, the resultant value is converted to its type. If necessary, the resultant value is adjusted to 
the length of the remainder operand, aligned at the assumed decimal point of the remainder operand, 
or both before being copied to it. If significant digits are truncated off the left end of the resultant 
value, a size (nex OCOA) exception is signaled. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled (in programs that 
request size exceptions to be signaled), the binary value contains the correct truncated result only if 
the decimal value contains 15 or fewer significant nonfractional digits. 


Resultant Conditions: The algebraic value of the numeric scalar quotient is 


° positive 
e negative 
e zero 
Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Spacing addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range X X X X 
06 Optimized addressability invalid X X X X 
08 Argument/parameter 
01 Parameter reference violation X Xx X X 
0c Computation 
02 Decimal data X X 
0A Size X X 
OB Zero divide x 
10 Damage encountered 
04 System object damage state X X X X X 
44 Partial system object damage X X X X X 
1C Machine-dependent exception 
03 Machine storage limit exceeded X 
20 Machine support 
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Exception 


22 


24 


2C 


2E 


36 


02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program execution 


04 Invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Divide with Remainder (DIVREM) 


Operands 

1 2 3 4 Other 
xX 
X 

X X X X 

X X X X 

X X X X 
X 

X X X X 

X X X X 
X 
X 
X 
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Edit (EDIT) 


Edit (EDIT) 


é Op Code (Hex) Operand 1 Operand 2 Operand 3 
10E3 Receiver Source Edit Mask 


Operand 1: Character variable scalar or data-pointer-defined character scalar. 
Operand 2: Numeric scalar or data-pointer-defined numeric scalar. 


Operand 3: Character variable scalar or data-pointer-defined character scalar. 


| ILE access 
LBEDIT ( 
var receiver : aggregate, 
var receiver_length : unsigned binary; 
var source : signed binary; OR 


packed decimal; 


| 

| 

| 

| 

| unsigned binary; OR 
| 

| var source attributes : aggregate; 

| 

| 

| 


var mask : aggregate; 
var mask_length : unsigned binary 
) 
| | OR : 
| | EDITPD ( 
, | var receiver : aggregate; 

Ss | receiver_length : unsigned binary; 
| var source : packed decimal; 
| source_length : unsigned binary; 
| var mask : aggregate; 
| mask_length : unsigned binary 
ie, 


Description: The value of a numeric scalar is transformed from its internal form to character form 
suitable for display at a source/sink device. The following general editing functions can be performed 
during transforming of the source operand to the receiver operand: 


¢ Unconditional insertion of a source value digit with a zone as a function of the source value’s alge- 
braic sign 
e Unconditional insertion of a mask operand character string 


¢ Conditional insertion of one of two possible mask operand character strings as a function of the 
source value’s algebraic sign 


¢ Conditional insertion of a source value digit or a mask operand replacement character as a func- 
tion of source value leading zero suppression 


¢ Conditional insertion of either a mask operand character string or a series of replacement charac- 
ters as a function of source value leading zero suppression 


¢ Conditional floating insertion of one of two possible mask operand character strings as a function 
of both the algebraic sign of the source value and leading zero suppression 


é The operation is performed by transforming the source (operand 2) under control of the edit mask 
(operand 3) and placing the result in the receiver (operand 1). 
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The mask operand (operand 3) is limited to no more than 256 bytes. 


Mask Syntax: The source field is converted to packed decimal format. The edit mask contains both 
control character and data character strings. Both the edit mask and the source fields are processed 
left to right, and the edited result is placed in the result field from left to right. If the number of digits in 
the source field is even, the four high-order bits of the source field are ignored and not checked for 
validity. All other source digits as well as the sign are checked for validity, and a decimal data (hex 
OCO2) exception is signaled when one is invalid. Overlapping of any of these fields gives unpredictable 
results. 


Nine fixed value control characters can be in the edit mask, hex AA through hex AD and hex AF 
through hex B3. Four of these control characters specify strings of characters to be inserted into the 
result field under certain conditions; and the other five indicate that a digit from the source field should 
be checked and the appropriate action taken. 


One variable value control character can be in the edit mask. This control character indicates the end 
of a string of characters. The value of the end-of-string character can vary with each execution of the 
instruction and is determined by the value of the first character in the edit mask. If the first character 
of the edit mask is a value less than hex 40, then that value is used as the end-of-string character. If 
the first character of the edit mask is a value equal to or greater than hex 40, then hex AE is used as 
the end-of-string character. 


A significance indicator is set to the off state at the start of the execution of this instruction. It remains 
in this state until a nonzero source digit is encountered in the source field or until one of the four 
unconditional digits (hex AA through hex AD) or an unconditional string (hex B3) is encountered in the 
edit mask. 


When significance is detected, the selected floating string is overlaid into the result field immediately 
before (to the left of) the first significant result character. 


When the significance indicator is set to the on state, the first significant result character has been 
reached. The state of the significance indicator determines whether the fill character or a digit from 
the source field is to be inserted into the result field for conditional digits and characters in conditional 
strings specified in the edit mask field. The fill character is a hex 40 until it is replaced by the first 
character following the floating string specification control character (hex B71). 


When the significance indicator is in the off state: 


¢ A conditional digit control character in the edit mask causes the fill character to be moved to the 
result field. 


e A character in a conditional string in the edit mask causes the fill character to be moved to the 
result field. 


When the significance indicator is in the on state: 


e A conditional digit control character in the edit mask causes a source digit to be moved to the 
result field. 


¢« A character in a conditional string in the edit mask is moved to the result field. 


The following control characters are found in the edit mask field. 


End-of-String Character: One of these control characters (a value less than hex 40 or hex AE) indi- 
cates the end of a character string and must be present even if the string is null. 


Static Field Character: 
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Hex AF This control character indicates the start of a static field. A static field is used to indicate that 
one of two mask character strings immediately following this character is to be inserted into 
the result field, depending upon the algebraic sign of the source field. If the sign is positive. 
the first string is to be inserted into the result field; if the sign is negative, the second string is 
to be inserted. 


Static field format: 
<Hex AF> <positive string>...<less than hex 40> <negative string>...<hex AE> 
OR 


<Hex AF> <positive string>...<hex AE> <negative string>...<hex AE> 


Floating String Specification Field Character: 


Hex B1 This control character indicates the start of a floating string specification field. The first char- 
acter of the field is used as the fill character; following the fill character are two strings delim- 
ited by the end-of-string control character. If the algebraic sign of the source field is positive, 
the first string is to be overlaid into the result field; if the sign is negative, the second string is 
to be overlaid. 


The string selected to be overlaid into the result field, called a floating string, appears imme- 
diately to the left of the first significant result character. If significance is never set, neither 
string is placed in the result field. 


Conditional source digit positions (hex B2 control characters) must be provided in the edit 
mask immediately following the hex B1 field to accommodate the longer of the two floating 
strings; otherwise, a length conformance exception is signaled. For each of these B2 strings, 
the fill character is inserted into the result field, and source digits are not consumed. This 
ensures that the floating string never overlays bytes preceding the receiver operand. 


Floating string specification field format: 


<Hex B1> <fill character> <positive string>... <end-of-string character> <negative 
string>...<end-of-string character> 


followed by 


<Hex B2>... 


Conditional String Character: 


Hex BO This control character indicates the start of a conditional string, which consists of any charac- 
ters delimited by the end-of-string control character. Depending on the state of the signif- 
icance indicator, this string or fill characters replacing it is inserted into the result field. If the 
significance indicator is off, a fill character for every character in the conditional string is 
placed in the result field. If the indicator is on, the characters in the conditional string are 
placed in the result field. 


Conditional string format: 


<Hex BO> <conditional string>...<end-of-string character > 


Unconditional String Character: 


Hex B3 This control character turns on the significance indicator and indicates the start of an uncondi- 
tional string that consists of any characters delimited by the end-of-string control character. 
This string is unconditionally inserted into the result field regardless of the state of the signif- 
icance indicator. If the indicator is off when a B3 control character is encountered, the appro- 
priate floating string is overlaid into the result field before (to the left of) the B3 unconditional 
string (or to the left of where the unconditional string would have been if it were not null). 


Unconditional string format: 


Chapter 2. Computation and Branching Instructions 2-156 


Edit (EDIT) 


<Hex B3> <unconditional string>...<end-of-string character> 


Control Characters That Correspond to Digits in the Source Field: 7 


Hex B2 


This control character specifies that either the corresponding source field digit or the floating 
String (nex B‘) fill character is inserted into the resuit field, depending on the state of the 
significance indicator. If the significance indicator is off, the fill character is placed in the 
result field; if the indicator is on, the source digit is placed. When a source digit is moved to 
the result field, the zone supplied is hex F. When significance (that is, a nonzero source digit) 
is detected, the floating string is overlaid to the left of the first significant character. 


Control characters hex AA, hex AB, hex AC, and hex AD turn on the significance indicator. If the indi- 
cator is off when one of these control characters is encountered, the appropriate floating string is over- 
laid into the result field before (to the left of) the result digit. 


Hex AA 


Hex AB 


Hex AC 


Hex AD 


This control character specifies that the corresponding source field digit is unconditionally 
placed in the 4 low-order bits of the result field with the zone set to a hex F. 


This control character specifies that the corresponding source field digit is unconditionally 
placed in the result field. If the sign of the source field is positive, the zoned portion of the 
digit is set to hex F (the preferred positive sign); if the sign is negative, the zone portion is set 
to hex D (the preferred negative sign). 


This control character specifies that the corresponding source field digit is unconditionally 
placed in the result field. If the algebraic sign of the source field is positive, the zone portion 
of the result is set to hex F (the preferred positive sign); otherwise, the source sign field is 
moved to the result zone field. 


This control character specifies that the corresponding source field digit is unconditionally 

placed in the result field. If the algebraic sign of the source field is negative, the zone is set ( 

to hex D (the preferred negative sign); otherwise, the source field sign is moved to the zone eg 
position of the result byte. J 


The following table provides an overview of the results obtained with the valid edit conditions and 
sequences. 


Table 2-1 (Page ?f of 3). Valid Edit Conditions and Results 


Mask 
Character 


AF 


AB 


Previous Resulting 

Significance Source Source Result Significance 

indicator Digit Sign Character(s) indicator 

Off/On Any Positive Positive string No Change 
inserted 

Off/On Any Negative Negative string No Change 
inserted 

Off 0-9 Positive Positive floating On 


string overlaid; hex 
F, source digit 


Off 0-9 Negative Negative floating On 
string overlaid; hex 
F, source digit 


On 0-9 Any Hex F, source digit On 
Off 0-9 Positive Positive floating On 


string overlaid; hex 
F, source digit 


Off 0-9 Negative Negative floating On 2) 
string overlaid; hex 
D, source digit 
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Mask 
Character 


AC 


AD 


BO 


B1 (including 
necessary B2s) 


B2 (not for a B1 
field) 


B3 


Previous 


Significance 


Indicator 


On 
On 


Off 


Off 


Off 


On 


Off 


Off 


Off 


Off 


Off 


Source 
Digit 


0-9 


0-9 
0-9 
0-9 


Any 


Any 


Any 


1-9 


Any 


Source 
Sign 


Positive 


Negative 


Positive 


Negative 


Positive 


Negative 


Positive 


Negative 


Positive 


Negative 


Any 


Any 


Any 


Any 


Positive 


Negative 


Any 


Positive 


Result 
Character(s) 


Hex F, source digit 


Hex D, source digit 


Positive floating 
string overlaid; hex 
F, source digit 


Negative floating 
string overlaid; 
source sign and digit 


Hex F, source digit 


Source sign and digit 


Positive floating 
string overlaid; 
source sign and digit 


Negative floating 
string overlaid; hex 
D, source digit 


Source sign and digit 


Hex D, source digit 


Insert fill character 
for each BO string 
character 


Insert BO character 
string 


Insert the fill char- 
acter for each B2 
character that corre- 
sponds to a char- 
acter in the longer of 
the two floating 
strings 


Insert fill character 


Overlay positive 
floating string and 
insert hex F, source 
digit 

Overlay negative 
floating string and 
insert hex F, source 
digit 

Hex F, source digit 


Overlay positive 
floating string and 
insert B3 character 
string 


Edit (EDIT) 


Resulting 


Significance 


Indicator 


On 
On 


On 


On 


No Change 


Off 


On 


On 


On 
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Table 2-1 (Page 3 of 3). Valid Edit Conditions and Results 


Previous Resulting 
Mask Significance Source Source Result Significance 
Character Indicator Digit Sign Character(s) Indicator 2) 
Off Any Negative Overlay negative On 


floating string and 
insert B3 character 
string 


On Any Any Insert B3 character On 
string 


Note: 


1. Any character is a valid fill character, including the end-of-string character. 

2. Hex AF, hex B1, hex BO, and hex B3 strings must be terminated by the end-of-string character even if they are 
null strings. 

3. If a hex B1 field has not been encountered (specified) when the significance indicator is turned on, the floating 
string is considered to be a nuili string and is therefore not used to overlay into the result field. 

4. If the positive and negative strings of a static field are of unequal length, additional static fields are necessary 
to ensure that the sum of the lengths of the positive strings equal the sum of the lengths of the negative 
strings; otherwise, a /ength conformance (0C08) exception is signaled because the receiver length does not 
correspond to the length implied by the edit mask and source field sign. 


The following figure indicates the valid ordering of control characters in an edit mask field. 


AA, AB, AC, AD 


Control Character Y 
Be Ba 


AF BO 8B! 


( hay 
4 nN 


Control 
Character X 
B2 
B3 
AACON-O 
Explanation: 


Condition Definition 


0 Both X and Y can appear in the edit mask field in either order. 
1 Y cannot precede X. 
2 X cannot precede Y. 
3 Both control characters (two B1’s) cannot appear in an edit mask field. 


Violation of any of the above rules will result in an edit mask syntax (hex OCO5) exception. 


Figure 2-6. Edit Mask Field Contro/ Characters 
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The following steps are performed when the editing is done: 
¢ Convert Source Value to Packed Decimal 


— The numeric value in the source operand is converted to a packed decimal intermediate value 
before the editing is done. If the source operand is binary, then the attributes of the interme- 
diate packed field before the edit are calculated as follows: 


Binary(2) packed (5,0) or 
Binary(4) packed (10,0) 


e Edit 


— The editing of the source digits and mask insertion characters into the receiver operand is 
done from left to right. 


e Insert Floating String into Receiver Field 


— Ifa floating string is to be inserted into the receiver field, this is done after the other editing. 


Edit Digit Count Exception: An edit digit count (hex 0C04) exception is signaled when: 


e The end of the source field is reached and there are more control characters that correspond to 
digits in the edit mask field. 


e The end of the edit mask field is reached and there are more digit positions in the source field. 
Edit Mask Syntax Exception: An edit mask syntax (hex 0C05) exception is signaled when an invalid 
edit mask control character is encountered or when a sequence rule is violated. 

Length Conformance Exception: A length conformance (hex 0C08) exception is signaled when: 
e The end of the edit mask field is reached and there are more character positions in the result field. 
e The end of the result field is reached and more positions remain in the edit mask field. 


e The number of B2s following a B1 field cannot accommodate the longer of the two floating strings. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Spacing addressing violation 
02 Boundary alignment 
03 Range 


04 External data object not found 


x KKK RK 
x K KK XK 
x K KK K 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation X X X 


0C Computation 
02 Decimal data X 
04 Edit digit count X 
05 Edit mask syntax X 


08 Length conformance Xx 
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Exception 


10 


ic 


20 


22 


24 


2E 


32 


36 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


02 Scalar attributes invalid 


Space management 


01 space extension/truncation 


Edit (EDIT) 


Operands 


1 2 3 Other 


X X X Xx 
X Xx Xx X 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
Xx X X 
X 
X X X 
X 
X 
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Exchange Bytes (EXCHBY) 


Exchange Bytes (EXCHBY) 


Op Code (Hex) Operand 1 Operand 2 


10CE 


Source 1 Source 2 


Operand 1: Character variable scalar (fixed-length) or numeric variable scalar. 


Operand 2: Character variable scalar (fixed-length) or numeric variable scalar. 


Description: The logical character string values of the two source operands are exchanged. The 
value of the second source operand is placed in the first source operand and the value of the first 


source operand is placed in the second operand. 


The operands can be either character or numeric. Any numeric operands are interpreted as logical 
character strings. Both operands must have the same length. 


Exceptions 


Operands 


Exception 1 2 Other 


06 


08 


1C 


20 


22 


24 


2E 


Addressing 

01 Spacing addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x KK XK 
x KX K XK 


Argument/parameter 


01 Parameter reference violation X Xx 


Damage encountered 
04 System object damage state X X X 
44 Partial system object damage X X X 


Machine-dependent exception 


03 Machine storage limit exceeded X 


Machine support 
02 Machine check xX 
03 Function check X 


Object access 

01 Object not found X X 
02 Object destroyed 
03 Object suspended X X 


08 object compressed X 


* 
> 


Pointer specification 
01 Pointer does not exist Xx X 


02 Pointer type invalid X X 


Resource control limit 


01 user profile storage limit exceeded X 
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Exchange Bytes (EXCHBY) 


Operands 
Exception 1 2 Other 
36 Space management 3 
01 space extension/truncation X 
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Exclusive Or (XOR) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5 | 


XOR Receiver Source 1 Source 2 

109B 

XORI Indicator Receiver Source 1 Source 2 Indicator targets 
189B options 

XORB Branch options Receiver Source 1 Source 2 Branch targets 
1C9B 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 
Operand 3: Character scalar or numeric scalar. 


Operand 4-5: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ {Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-4] 
XORS Receiver/Source 1 Source 2 

119B 

XORIS Indicator options Receiver/Source 1 Source 2 Indicator targets 
199B 

XORBS Branch options Receiver/Source 1 Source 2 Branch targets 
1D9B 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 


Operand 3-4: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ /ndicator Form-Numeric variable scalar or character variable scalar. 


Description: The Boolean EXCLUSIVE OR operation is performed on the string values in the source 
operands. The resulting string is placed in the receiver operand. . 


The operands may be character or numeric scalars. They are both interpreted as bit strings. Sub- 
stringing is supported for both character and numeric operands. 


The length of the operation is equal to the length of the longer of the two source operands. The 
shorter of the two operands is padded on the right. The operation begins with the two source oper- 
ands left-adjusted and continues bit by bit until they are completed. 
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Exclusive Or (XOR) 


The bit values of the result are determined as follows: 


Source 1 Bit Source 2 Bit Result Bit J 
0 0 0 
0 1 1 
1 0 1 
1 1 0 


The result value is then placed (left-adjusted) in the receiver operand with truncating or padding taking 
place on the right. 


The pad value used in this instruction is a hex 00. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1, 2, and 3. The effect of specifying a null substring reference for one source 
operand is that the other source operand is EXCLUSIVE ORed with an equal length string of all hex 
00s. When a null substring reference is specified for both source operands, the result is all zero and 
the instruction’s resultant condition is zero. When a null substring reference is specified for the 
receiver, a result is not set and the instruction’s resultant condition is zero regardless of the vaiues of 
the source operands. 


If operands overlap but do not share all of the same bytes, results of operations performed on these 
operands are not predictable. If overlapped operands share all of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


Cc 


When the receiver operand is a numeric variable scalar, it is possible that the result produced will not 
be a valid value for the numeric type. This can occur due to padding with hex 00, due to truncation, or 
due to the resultant bit string produced by the instruction. The instruction completes normally and 
signals no exceptions for these conditions. 


Resultant Conditions 


« Zero-The bit value for the bits of the scalar receiver operand is either all zero or a null substring 
reference is specified for the receiver. 


e Not zero-The bit value for the bits of the scalar receiver operand is not all zero. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X X 
03 range X Xx X 
06 optimized addressability invalid X Xx X 
08 Argument/parameter 
01 parameter reference violation X X X 
10 Damage encountered 2 | 
04 system object damage state X X X X 
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Exception 


1C 


20 


22 


24 


2C 


2E 


36 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Exclusive Or (XOR) 


Operands 


1 2 3 Other 


X X X X 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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Extended Character Scan (ECSCAN) 


Jo 


Op Code Extender Operand 1 Operand 2 Operand 3 Operand 4 Operand [5-7] 

(Hex) 

ECSCAN Receiver Base Compare Mode 

10D4 operand operand 

ECSCANB Branch Receiver Base Compare Mode Branch 

1CD4 options operand Operand targets 

ECSCANI Indicator Receiver Base Compare Mode Indicator 

18D4 options operand operand targets 

Operand /: Binary variable scalar or binary array. 

Operand 2: Character variable scalar. 

Operand 3: Character scalar. 

Operand 4: Character(1) scalar. 

Operand 5-7: 

e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 

number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: This instruction scans the string value of the base operand for occurrences of the string 
value of the compare operand and indicates the relative locations of these occurrences in the receiver 
operand. The character string value of the base operand is scanned for occurrences of the character 
string value of the compare operand under control of the mode operand and mode control characters 
embedded in the base string. 


The base and compare operands must both be character strings. The length of the compare operand 
must not be greater than that of the base string. The base and compare operand are interpreted as 
containing a mixture of 1-byte (simple) and 2-byte (extended) character codes. The mode, simple or 
extended, with which the string is to be interpreted, is controlled initially by the mode operand and 
thereafter by mode control characters embedded in the strings. The mode control characters are as 
follows: 


« Hex OE = Shift out of simple character mode to extended mode. 


e Hex OF = Shift into simple character mode from extended mode. This is recognized only if it occurs 
in the first byte position of an extended character code. 


The format of the mode operand is as follows: 


e Mode operand Char(‘1) 
— Operand 2 initial mode indicator Bit O 
O = Operand starts in simple character mode. 
1 = Operand starts in extended character mode. 
— Operand 3 initial mode indicator Bit 1 
O = Operand starts in simple character mode. 
1 = Operand starts in extended character mode. 
— Reserved (binary 0) Bits 2-7 
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Extended Character Scan (ECSCAN) 


The operation begins at the left end of the base string and continues character by character. left to 
right. When the base string is interpreted in simple character mode, the operation moves through the 
base string 1 byte at a time. When the base string is interpreted in extended character mode. the 
operation moves through the base string 2 bytes at a time. 


The compare operand value is the entire byte string specified for the compare operand. The mode 
operand determines the initial mode of the compare operand. The first character of the compare 
operand value is assumed to be a valid character for the initial mode of the compare operand and not 
a mode control character. Mode control characters in the compare operand value participate in com- 
parisons performed during the scan function except that a mode control character as the first character 
of the compare operand causes unpredictable results. 


The base string is scanned until the mode of the characters being processed is the same as the initial 
mode of the compare operand value. The operation continues comparing the characters of the base 
string with those of the compare operand value. The starting character of the characters being com- 
pared in the base string is always a valid character for the initial mode of the compare operand value. 
A mode controi character encountered in the base string that changed the base string mode to match 
the initial mode of the compare operand value does not participate in the comparison. The length of 
the comparison is equal to the length of the compare operand value and the comparison is performed 
the same as performed by the Compare Bytes Left Adjusted instruction. 


lf a set of bytes that matches the compare operand value is found, the binary value for the relative 
location of the leftmost base string character of the set of bytes is placed in the receiver operand. 


If the receiver operand is a scalar, only the first occurrence of the compare operand is noted. If the 
receiver operand is an array, aS many occurrences as there are elements in the array are noted. 


If a mode change is encountered in the base string, the base string is again scanned until the mode of 
the characters being processed is the same as the initial mode of the compare operand value, and 
then the comparisons are resumed. 


The operation continues until no more occurrences of the compare operand value can be noted in the 
receiver operand or until the number of bytes remaining to be scanned in the base string is less than 

the length of the compare operand value. When the second condition occurs, the receiver value is set 
to zero. If the receiver operand is an array, all its remaining elements are also set to Zero. 


If the escape code encountered result condition is specified (through a branch or indicator option), ver- 
ifications are performed on the base string as it is scanned. Each byte of the base string is checked 
for a value less than hex 40. When a value less than hex 40 is encountered, it is then determined if it 
is a valid mode control character. 


If a byte value of less than hex 40 is not a valid mode control character, it is considered to be an 
escape code. The binary value for the relative location of the character (simple or extended) being 
interrogated is placed in the receiver operand, and the appropriate action (indicator or branch) is per- 
formed according to the specification of the escape code encountered result condition. If the receiver 
operand is an array, the next array element after any elements set with locations or prior occurrences 
of the compare operand, is set with the location of the character containing the escape code and all 
the remaining array elements are set to zero. 


If the escape encountered result condition is not specified, verifications of the character codes in the 
base string are not performed. 
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Extended Character Scan (ECSCAN) 


Resultant Conditions 
e« Positive-The numeric value(s) of the receiver operand is positive. } 


e Zero-The numeric value(s) of the receiver operand is zero. In the case where the receiver operand 
is an array, the resultant condition is zero if all elements are zero. 


« Escape code encountered-An escape character code value was encountered during the scanning of 
the base string. 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment violation 


03 range 


x KK XK 
x KX XK OK 
x KK OK 
x KK XK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X X 


0C Computation 
08 length conformance xX X X 


10 Damage encountered 
04 System object damage state X ) 


44 partial system object damage X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check xX 
03 function check Xx 


22 Object access 
01 object not found X X X X 
02 object destroyed 
03 object suspended X X X X 


08 object compressed x 


x< 
x 
~< 
~*~ 


24 Pointer specification 
01 pointer does not exist X X X X 
02 pointer type invalid X X X X 


2C Program execution 


04 invalid branch target X 


2E Resource control limit 
01 user profile storage limit exceeded X 3 


32 Scalar specification 
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c 


Exception 


36 


01 scalar type invalid 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Extended Character Scan (ECSCAN) 


Operands 


1 2 3 4 Other 


X X X X 
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Extract Exponent (EXTREXP) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
EXTREXP Receiver source 

1072 

EXTREXPB Branch options Receiver Source Branch targets 
1C€72 

EXTREXPI Indicator options Receiver Source Indicator targets 
1872 


Operand ?: Binary variable scalar. 
Operand 2: Floating-point scalar. 


Operand 3-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: This instruction extracts the exponent portion of a floating-point scalar source operand 
and places it into the receiver operand as a binary variable scalar. 


The operands must be the numeric types indicated because no conversions are performed. 


i 


The source floating-point field is interrogated to determine the binary floating-point value represented a 
and either a signed exponent, for number values, or a special identifier, for infinity and NaN values, is 
placed in the binary variable scalar receiver operand. 


The value to be assigned to the receiver, is dependent upon the floating-point value represented in the 
source operand as described below. It is a signed binary integer value and a numeric assignment of 
the value is made to the receiver. 


When the source represents a normalized number, the biased exponent contained in the exponent field 
of the source is converted to the corresponding signed exponent by subtracting the bias of 127 for 
short or 1023 for long to determine the value to be returned. The resulting value ranges from -126 to 
+127 for short format, -1022 to +1023 for long format. When the receiver is unsigned binary, a nega- 
tive exponent will result in a size (hex OCOA) exception unless size exceptions are suppressed by using 
the suppress binary size exception program attribute on the Create Program (CRTPG) instruction. 


When the source represents a denormalized number, the value to be returned is determined by 
adjusting the signed exponent of the denormalized number. The signed exponent of a denormalized 
number is a fixed value of -126 for the short format and -1022 for the long format. It is adjusted to the 
value the signed exponent would be if the source value was adjusted to a normalized number. The 
resulting value ranges from -127 to -149 for short format, -1023 to -1074 for long format. 


When the source represents a value of zero, the value returned is zero. 
When the source represents infinity, the value returned is +32767. 


When the source represents a not-a-number, the value returned is -32768 for a signed binary receiver. -_ 
For an unsigned binary(2) a value of 32768 is returned, and for a unsigned binary(4) a value of J 
4294934528 is returned. 
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Resultant Conditions 


Exceptions 


Exception 


06 


08 


10 


1C 


20 


22 


24 


2C 


2E 


32 


Addressing 

01 space addressing violation 
02 boundary alignment violation 
03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 System object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


Extract Exponent (EXTREXP) 


Normalized-The source operand value represents a normalized binary floating-point number. The 
signed exponent is stored in the receiver. 


Denormalized-The source operand value represents a denormalized binary floating-point number. 
An adjusted signed exponent is stored in the receiver. 


Infinity-The source operand value represents infinity. The receiver is set with a value of +32767. 


NaN-The source operand value represents a not-a-number. The receiver is set with a value of 
-32768 when signed binary, with a value of 32768 when unsigned binary(2), and with a value of 
4294934528 when unsigned binary(4). 


Operands 
1 2 Other 


X X 

X X 

X X 

X X 

X X 
X 
X 
X 
X 
X 

X X 

X X 

X X 
X 

X X 

X X 
X 
X 
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Extract Exponent (EXTREXP) 


Operands 
Exception 1 2 Other 
01 scalar type invalid X X 
J 
36 Space management 
01 space extension/truncation xX 


= 
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Extract Magnitude (EXTRMAG) 


( Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
EXTRMAG Receiver Source 
1052 
EXTRMAGI Indicator options Receiver Source Indicator targets 
1852 
EXTRMAGB Branch options Receiver Source Branch targets 
1C52 


Operand 7: Numeric variable scalar. 
Operand 2: Numeric scalar. 


Operand 3-6: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 
Op Code (Hex) Extender Operand 1 Operand [2-5] 
EXTRMAGS Receiver/Source 
1152 

= EXTRMAGIS Indicator options Receiver/Source Indicator targets 
1952 
EXTRMAGBS Branch options Receiver/Source Branch targets 
1D52 


Operand ?: Numeric variable scalar. 


Operand 2-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 
Description: The numeric value of the source operand is converted to its absolute value and placed in 
the numeric variable scalar receiver operand. 
The absolute value is formed from the source operand as follows: 
e Signed binary 
— Extract the numeric value and form twos complement if the source operand is negative. 
e Unsigned signed binary 
— Extract the numeric value. 


Cc e Packed/Zoned 


— Extract the numeric value and force the source operand’s sign to positive. 


Chapter 2. Computation and Branching Instructions 2-174 


Extract Magnitude (EXTRMAG) 


e Floating-point 
— Extract the numeric value and force the significand sign to positive. 


The result of the operation is copied into the receiver operand according to the rules of the Copy 
Numeric Value instruction. If this operand is not the same type as that used in performing the opera- 
tion, the resultant value is converted to its type. If necessary, the resultant value is adjusted to the 
length of the receiver operand, or aligned at the assumed decimal point of the receiver operand, or 
both before being copied to it. If significant digits are truncated on the left end of the resultant value, a 
size (hex OCOA) exception is signaled. An attempt to extract the magnitude of a maximum negative 
binary value to a binary scalar of the same size also results in a size (hex OCOA) exception. 


When the source floating-point operand represents not-a-number, the sign field of the source is not 
forced to positive and this value is not altered in the receiver. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 


For a fixed-point operation, if significant digits are truncated from the left end of the resultant value, a 
size (hex OCOA) exception is signaled. An attempt to extract the absolute value of a maximum negative 
binary value into a binary scalar of the same size also results in a size (hex OCOA) exception. 


For floating-point operations that involve a fixed-point receiver field, if nonzero digits would be trun- 
cated from the left end of the resultant value, an invalid floating-point conversion (OCOC) exception is 
signaled. 


For a floating-point receiver operand, if the exponent of the resultant value is either too large or too 
small to be represented in the receiver field, the floating-point overflow (hex O0COQ8) or the floating-point 
underflow (hex 0C07) exception is signaled. 
Resultant Conditions 

¢ Positive-The algebraic value of the receiver operand is positive. 

« Zero-The algebraic value of the receiver operand is zero. 


e Unordered-The value assigned a floating-point receiver operand is NaN. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation xX X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation xX X 
0c Computation 

02 decimal data x 

06 floating-point overflow X 

07 floating-point underflow X 
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Exception 


10 


1c 


20 


22 


24 


2C 


2E 


36 


09 floating-point invalid operand 
0A size 
OC invalid floating point conversion 


OD floating-point inexact result 


Damage encountered 
04 system object damage 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Extract Magnitude (EXTRMAG) 


Operands 
1 2 Other 
X 

X 

X 

X 

X X X 

X X X 
X 
X 
X 

X X 

X X 

X X 
X 

X X 

X X 
X 
X 
X 
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Multiply (MULT) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-7] 
MULT Product Multiplicand Multiplier 

1048 

MULTR Product Multiplicand Multiplier 

124B 

MULTI Indicator Product Multiplicand Multiplier Indicator targets 
184B options 

MULTIR Indicator Product Multiplicand Multiplier Indicator targets 
1A4B options 

MULTB Branch options Product Multiplicand Multiplier Branch targets 
1C4B 

MULTBR Branch options Product Multiplicand Multiplier Branch targets 
1E4B 


Operand 1: Numeric variable scalar. 
Operand 2: Numeric scalar. 
Operand 3: Numeric scalar. 


Operand 4-7: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
MULTS Product/Multiplicand Multiplier 

104B 

MULTSR Product/Multiplicand Multiplier 

134B 

MULTIS Indicator options Product/Multiplicand Multiplier Indicator targets 
194B 

MULTISR Indicator options Product/Multiplicand Multiplier Indicator targets 
1B4B ' 
MULTBS Branch options Product/Multiplicand Multiplier Branch targets 
1D4B 

MULTBSR Branch options Product/Multiplicand Multiplier Branch targets 
1F4B 


Operand 1: Numeric variable scalar. 
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Operand 2: Numeric scalar. 


Operand 3-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 
Description: The Product is the result of multiplying the Multiplicand and the Multiplier. 
Operands can have floating-point, packed or zoned decimal, signed or unsigned binary type. 
Source operands are the Multiplicand and Multiplier. The receiver operand is the Product. 


If operands are not of the same type, source operands are converted according to the following rules: 


1. If any one of the operands has floating point type, source operands are converted to floating point 
type. 


2. Otherwise, if any one of the operands has zoned or packed decimal type, source operands are 
converted to packed decimal. 


3. Otherwise, the binary operands are converted to a like type. Note: unsigned binary(2) scalars are 
logically treated as signed binary(4) scalars. 


Source operands are multiplied according to their type. Floating point operands are multiplied using 
floating point multiplication. Packed decimal operands are multiplied using packed decimal multipli- 
cation. Unsigned binary multiplication is used with unsigned source operands. Signed binary oper- 
ands are multiplied using two’s complement binary multiplication. 


Better performance can be obtained if all operands have the same type. Signed and unsigned binary 
multiplication execute faster than either packed decimal or floating point multiplication. 


Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. 


If the multiplicand operand or the multiplier operand has a value of 0, the result of the multiplication is 
a zero product. 


For a decimal operation, no alignment of the assumed decimal point is performed for the multiplier and 
multiplicand operands. 


The operation occurs using the specified lengths of the multiplicand and multiplier operands with no 
logical zero padding on the left necessary. 


Floating-point multiplication uses exponent addition and significand multiplication. 


For nonfloating-point computations and for significand multiplication for floating-point operations, the 
multiplication operation is performed according to the rules of algebra. Unsigned binary operands are 
treated as positive numbers for the algebra. 


The result of the operation is copied into the product operand. lf this operand is not the same type as 
that used in performing the operation, the resultant value is converted to its type. If necessary, the 
resultant value is adjusted to the length of the product operand, aligned at the assumed decimal point 
of the product operand, or both before being copied to it. 


For the optional round form of the instruction, specification of a floating-point receiver operand is 
invalid. 
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For fixed-point operations in programs that request to be notified of size exceptions. if nonzero digits 
are truncated from the left end of the resultant value, a size (nex OCOA) exception is signaled. 


For floating-point operations involving a fixed-point receiver field (if nonzero digits would be truncated 
from the left end of the resultant value), an invalid floating-point conversion (hex OCOC) exception is 
Signaled. 


For a floating-point product operand, if the exponent of the resultant value is either too large or too 
small to be represented in the product field, the floating-point overflow (hex OCO6) or the floating-point 
underflow (hex 0C07) exception is signaled. 


If operands overlap but do not share all of the same bytes, results of operations performed on these 
Operands are not predictable. If overlapped operands share all of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 
Resultant Conditions 

¢ Positive-The algebraic value of the numeric scalar product is positive. 

e Negative-The algebraic value of the numeric scalar product is negative. 

e Zero-The algebraic value of the numeric scalar product is zero. 


e Unordered-The value assigned a floating-point product operand is NaN. 


Exceptions 
Operands 
Exception 1 2 3 (4, 5] Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X X 
03 range X X X 
06 optimized addressability invalid X X X 
08 Argument/parameter 
01 parameter reference violation X X X 
0c Computation 
02 decimal data X X 
06 floating-point overflow X 
07 floating-point underflow X 
09 floating-point invalid operand X X X 
0A size X 
OC invalid floating-point conversion X 
OD floating-point inexact result X 
10 Damage encountered 
04 system object damage state X X X X 
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Exception 


iC 


20 


22 


24 


2C 


2E 


36 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Multiply (MULT) 


Operands 

1 2 3 [4,5] Other 

X X X X 
X 
X 
X 

X X X 

X X X 

X X X 
X 

X X X 

X X X 
X 
X 
X 
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Negate (NEG) 


Negate (NEG) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand (3-6 | 
NEG Receiver Source 

1056 

NEGI Indicator options Receiver Source Indicator targets 
1856 

NEGB Branch options Receiver Source Branch targets 
1C56 


Operand ?: Numeric variable scalar. 
Operand 2: Numeric scalar. 


Operand 3-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand [2-5] 
NEGS Receiver/Source 

1156 

NEGIS Indicator options Receiver/Source Indicator targets 
1956 

NEGBS Branch options Receiver/Source Branch targets 
1D56 


Operand 7: Numeric variable scalar. 


Operand 2-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e /ndicator Form-Numeric variable scalar or character variable scalar. 


Description: The numeric value in the source operand is changed as if it had been multiplied by a 
negative one (-1). The result is placed in the receiver operand. 


The sign changing of the source operand value (positive to negative and negative to positive) is per- 
formed as follows: 
e Binary 
— Extract the numeric value and form the twos complement of it. 
e Packed/Zoned 


— Extract the numeric value and force its sign to positive if it is negative or to negative if it is 
positive. 


e Floating-point 
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— €xtract the numeric value and force the significand sign to positive if it is negative or to nega- 
tive if it is positive. 

The result of the operation is copied into the receiver operand. If this operand is not the same type as 
that used in performing the operation, the resultant value is converted to its type. If necessary, the 
resultant value is adjusted to the length of the receiver operand, aligned at the assumed decimal point 
of the receiver operand, or both before being copied to it. If significant digits are truncated on the left 
end of the resultant vaiue, a size (hex OCOA) exception is signaled. An attempt to negate a maximum 
negative signed binary value to a signed binary scalar of the same size also results in a size (hex 
OCOA) exception. When the receiver is binary the size exception may be suppressed by using the sup- 
press binary size exception attribute on the Create Program (CRTPG) instruction. If a packed or zoned 
0 is negated, the result is always positive 0. 


When the source floating-point operand represents not-a-number, the sign field of the source is not 
forced to positive and this value is not altered in the receiver. 


For a fixed-point operation, if significant digits are truncated from the left end of the resultant value, a 
size (hex OCOA) exception is signaled. An attempt to negate a maximum negative binary value into a 
binary scalar of the same size also results in a size (hex OCOA) exception. 


For floating-point operations that involve a fixed-point receiver field, if nonzero digits would be trun- 
cated from the left end of the resultant value, an invalid floating-point conversion (hex OCOC) exception 
is signaled. 


For a floating-point receiver operand, if the exponent of the resultant value is either too large or too 
small to be represented in the receiver field, the floating-point overflow (hex 0CO6) and the floating- 
point underflow (hex 0C07) exceptions are signaled. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled or if the size 
exception was suppressed, the binary value contains the correct truncated result only if the decimal 
value contains 15 or fewer significant nonfractional digits. 
Resultant Conditions 

e Positive-The algebraic value of the receiver operand is positive. 

e Negative-The algebraic value of the receiver operand is negative. 

e Zero-The algebraic value of the receiver operand is zero. 


e Unordered-The value assigned a floating-point receiver operand is NaN. 


Exceptions 
, Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
0C Computation 

02 decimal data X 
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Exception 


10 


1¢C 


20 


22 


24 


2C 


2E 


36 


06 floating-point overflow 

07 flaating-point underflow 

03 floating-point invalid operand 
0A size 

OC invalid floating-point conversion 


OD floating-point inexact result 


Damage encountered 
04 system object damage 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Negate (NEG) 


Operands 

1 2 Other 

X 

X 

X X 

X 

X 

X 

X X X 

X X X 
X 
X 
X 

X X 

X X 

X X 
X 

X X 

X X 
X 
X 
X 
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Not (NOT) 


Not (NOT) 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-4] 
NOT Receiver Source 

108A 

NOTI Indicator options Receiver Source Indicator targets 
188A 

NOTB Branch options Receiver Source Branch targets 
1C8A 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character variable scalar or numeric variable 


Operand 3-4: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand [2-3] 
NOTS Receiver/Source 

118A 

NOTIS Indicator options Receiver/Source Indicator targets 
198A 

NOTBS Branch options Receiver/Source Branch targets 
1D8A 


Operand 1: Character variable scalar or numeric variable scalar. 


Operand 2-3: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The Boolean NOT operation is performed on the string value in the source operand. The 
resulting string is placed in the receiver operand. 


The operands may be character or numeric scalars. They are both interpreted as bit strings. Sub- 
stringing is supported for both character and numeric operands. 


The length of the operation is equal to the length of the source operand. 


The bit values of the result are determined as follows: 
Source Bit Result Bit 

0 1 

1 0 
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The result value is then placed (left-adjusted) in the receiver operand with truncating or padding taking 
place on the right. The pad value used in this instruction is a hex 00 byte. 


Substring operand references that allow for a null substring reference (a length value of zero) may be a 
specified for operands 1 and 2. The effect of specifying a null substring reference for the source 

operand is that the result is all zero and the instruction’s resultant condition is zero. When a null 

substring reference is specified for the receiver, a result is not set and the instruction’s resultant condi- 


tion is zero regardless of the value of the source operand. 


When the receiver operand is a numeric variable scalar, it is possible that the result produced will not 
be a valid value for the numeric type. This can occur due to padding with hex 00, due to truncation, or 
due to the resultant bit string produced by the instruction. The instruction completes normally and 
signals no exceptions for these conditions. 


Resultant Conditions 


e Zero-The bit value for the bits of the scalar receiver operand is either all zero or a null substring 
reference is specified for the receiver. 


¢ Not zero-The bit value for the bits of the scalar receiver operand is not all zero. 


Exceptions 

Operands 
Exception 1 2 Other 
06 Addressing 


01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x KK RK 
x KK XK 


08 Argument/parameter 


01 parameter reference violation X X 


10 Damage encountered 
04 system object damage state X X X 
44 partial system object damage X X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check Xx 


22 Object access 
01 object not found X X 
02 object destroyed 


a 
~ 


03 object suspended X X 


08 object compressed X 


24 Pointer specification ) 
01 pointer does not exist X X 


02 pointer type invalid X X 
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Exception 
2C Program execution 
04 invalid branch target 


2E Resource control limit 


01 user profile storage limit exceeded 


36 Space management 


01 space extension/truncation 


Not (NOT) 


Operands 
1 2 Other 
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Or (OR) 

Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] J 
OR Receiver Source 1 Source 2 

1097 

ORI Indicator Receiver Source 1 Source 2 Indicator targets 

1897 options 

ORB Branch options Receiver Source 1 Source 2 Branch targets 

1C97 


Operand ?: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 
Operand 3: Character scalar or numeric scalar. 


Operand 4-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-4] t 
ORS Receiver/Source 1 Source 2 J 
1197 

ORIS Indicator options Receiver/Source 1 Source 2 Indicator targets 

1997 

ORBS Branch options Receiver/Source 1 Source 2 Branch targets 

1D97 


Operand 1: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 


Operand 3-4: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The Boolean OR operation is performed on the string values in the source operands. 
The resulting string is placed in the receiver operand. 


The operands may be character or numeric scalars. They are both interpreted as bit strings. Sub- 
stringing is supported for both character and numeric operands. 


The length of the operation is equal to the length of the longer of the two source operands. The = | 
shorter of the two operands is logically padded on the right with hex 00. The excess bytes in the 
longer operand are assigned to the results. 
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The bit values of the result are determined as follows: 


Source 1 Bit Source 2 Bit Result Bit 
0 0 0 
0 { 1 


1 0 1 
1 1 1 


The result value is then placed (left-adjusted) in the receiver operand with truncating or padding taking 
place on the right. The pad value used in this instruction is a hex 00. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 1, 2, and 3. The effect of specifying a null substring reference for one source 
operand is that the other source operand is ORed with an equal length string of all hex 00s. This 
causes the value of the other operand to be assigned to the result. When a null substring reference is 
specified for both source operands, the result is all zero and the instruction’s resultant condition is 
zero. When a null substring reference is specified for the receiver, a result is not set and the 
instruction’s resultant condition is zero regardless of the values of the source operands. 


lf operands overlap but do not share all of the same bytes, results of operations performed on these 
operands are not predictable. If overlapped operands share all of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


When the receiver operand is a numeric variable scalar, it is possible that the result produced will not 
be a valid value for the numeric type. This can occur due to padding with hex 00, due to truncation, or 
due to the resultant bit string produced by the instruction. The instruction completes normally and 
Signals no exceptions for these conditions. 


Resultant Conditions 


e Zero-The bit value for the bits of the scalar receiver operand is either all Zero or a null substring 
reference is specified for the receiver. 


e Not zero-The bit value for the bits of the scalar receiver operand is not all zero. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 space addressing violation 
02 boundary alignment 


03 range 


x K KK 
x KK K 
x KK K 


06 optimized addressability invalid 


08 Argument/parameter 
01 parameter reference violation X X X 
10 Damage encountered 
04 system object damage state X X x X 
44 partial system object damage X xX X X 
1C Machine-dependent exception 
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Operands 
Exception 1 2 3 Other 
03 machine storage limit exceeded X ) 
20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 abject not found X X X 
02 object destroyed 
03 object suspended X X X 


08 object compressed X 


~*< 
x 
x 


24 Pointer specification 
01 pointer does not exist X X X 
02 pointer type invalid X X X 


2C Program execution 


04 invalid branch target X 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation xX ‘ 
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Remainder (REM) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-6] 
REM Remainder Dividend Divisor 

1073 

REMI Indicator Remainder Dividend Divisor Indicator targets 
1873 options 

REMB Branch options Remainder Dividend Divisor Branch targets 
1073 


Operand 7: Numeric variable scalar. 
Operand 2: Numeric scalar. 
Operand 3: Numeric scalar. 


Operand 4-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ /ndicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-5 ] 
REMS Remainder/Dividend Divisor 

1173 

REMIS Indicator options Remainder/Dividend Divisor Indicator targets 
1973 

REMBS Branch options Remainder/Dividend  Divisor Branch targets 
1D73 


Operand f: Numeric variable scalar. 
Operand 2: Numeric scalar. 


Operand 3-5: 


* Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The Remainder is the result of dividing the Dividend by the Divisor and placing the 
remainder in operand 1. 


Operands can have packed or zoned decimal, signed or unsigned binary type. 
Source operands are the Dividend and Divisor. The receiver operand is the Remainder. 


lf operands are not of the same type, source operands are converted according to the following rules: 
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1. If any one of the operands has zoned or packed decimal type. source operands are converted to 
packed decimal. 


2. Otherwise, the binary operands are converted to a like type. Note: unsigned binary(2) scalars are 
logically treated as signed binary(4) scalars. 


source operands are divided according to their type. Packed decimal operands are divided using 
packed decimal division. Unsigned binary division is used with unsigned source operands. Signed 
binary operands are divided using two’s complement binary division. 


Better performance can be obtained if all operands have the same type. Signed and unsigned binary 
division execute faster than packed decimal division. 


Floating-point is not supported for this instruction. 


lf the divisor has a numeric value of 0, a zero divide (hex OCOB) exception is signaled. If the dividend 
has a value of 0, the result of the division is a zero value remainder. 


For a decimal operation, the internal quotient value produced by the divide operation is always calcu- 
lated with a precision of zero fractional digit positions. If necessary, internal alignment of the assumed 
decimal point for the dividend and divisor operands is performed to insure the correct precision for the 
resultant quotient value. These internal alignments are not subject to detection of the decimal point 
alignment exception. An internal quotient and the corresponding remainder value will be calculated 
for any combination of decimal attributes which may be specified for the instruction’s operands. 
However, as described below, the assignment of the remainder value is limited to that portion of the 
remainder value which fits in the remainder operand. 


If the dividend is shorter than the divisor, it is logically adjusted to the length of the divisor. 


The division operation is performed according to the rules of algebra. Unsigned binary is treated as a 
positive number for the algebra. Before the remainder is calculated, an intermediate quotient is calcu- 
lated. The attributes of this quotient are derived from the attributes of the dividend and divisor oper- 
ands as follows: 


Intermediate 


Dividend Divisor Quotient 

IM,SIM or SBIN(2) IM,SIM or SBIN(2) SBIN(2) 

IM,SIM or SBIN(2) SBIN(4) SBIN(4) 
IM,SIM,SBIN(2) or UBIN(2) DECIMAL(P2,Q2) DECIMAL(5+-Q2,0) 
IM,SIM,SBIN(2) or SBIN(4) UBIN(2) or UBIN(4) UBIN(4) 

UBIN(2) or UBIN(4) IM,SIM,SBIN(2) or UBIN(4) 

SBIN(4) 
UBIN(2) or UBIN(4) UBIN(2) or UBIN(4) UBIN(4) 
SBIN(4) IM,SIM or SBIN(2) SBIN(4) 


SBIN(4) or UBIN(4) 
DECIMAL(P1,Q1) 


DECIMAL(P1,Q1) 
DECIMAL(P1,Q1) 


IM = IMMEDIATE 


DECIMAL(P2,Q2) 


IM,SIM,SBIN(2) or 
UBIN(2) 


SBIN(4) or UBIN(4) 
DECIMAL(P2,Q2) 


SIM = SIGNED IMMEDIATE 


SBIN = SIGNED BINARY 


DECIMAL(10+@2,0) 
DECIMAL(P1,0) 


DECIMAL(P1,0) 
DECIMAL({P1-Q1+0,0) 
Where Q = Larger of Q1 or Q2 
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UBIN = UNSIGNED BINARY 
DECIMAL = PACKED OR ZONED 


After the intermediate quotient numeric value has been determined, the numeric value of the 
remainder operand is calculated as follows: 


Remainder = Dividend - (Quotient*Divisor) 


When signed arithmetic is used, the sign of the remainder is the same as that of the dividend unless 
the remainder has a value of 0. When the remainder has a value of 0, the sign of the remainder is 
positive. 


The resultant value of the calculation is copied into the remainder operand. If this operand is not the 
same type as that used in performing the operation, the resultant value is converted to its type. If 
necessary, the resultant value is adjusted to the length of the remainder operand, aligned at the 
assumed decimal point of the remainder operand, or both before being copied to it. 


If significant digits are truncated on the left end of the resultant value, a size (hex OCOA) exception is 
signaled for those programs that request to be notified of size exceptions. 


lf a decimal to binary conversion causes a size (hex OCOA) exception to be signaled in programs that 
request to be notified of size exceptions, the binary value contains the correct truncated result only if 
the decimal value contains 15 or fewer significant nonfractional digits. 
Resultant Conditions 

e Positive-The algebraic value of the numeric scaler remainder is positive. 

e Negative-The algebraic value of the numeric scaler remainder is negative. 


« Zero-The algebraic value of the numeric scaler remainder is Zero. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X X 
03 range X X X 
06 optimized addressability invalid X X X 
08 Argument/parameter 
01 parameter reference violation X X X 
0c Computation 
02 decimal data Xx X 
0A size X 
0B zero divide X 
10 Damage encountered 
04 system object damage state X X X X 
44 partial system object damage X X X X 
1c Machine-dependent exception 
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Exception 


20 


22 


24 


2c 


2E 


36 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Remainder (REM) 


Operands 
1 2 3 Other 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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Scale (SCALE) 


Scale (SCALE) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-7] 
SCALE Receiver Source Scale factor 

1063 

SCALE! Indicator Receiver Source Scale factor Indicator targets 
1863 options 

SCALEB Branch options Receiver Source Scale factor Branch targets 
1C63 


Operand 1: Numeric variable scalar. 
Operand 2: Numeric scalar. 
Operand 3: Binary(2) scalar. 


Operand 4-7: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
SCALES Receiver/Source Scale factor 

1163 

SCALEIS Indicator options Receiver/Source Scale factor Indicator targets 
1963 

SCALEBS Branch options Receiver/Source Scale factor Branch targets 
1D63 


Operand 1: Numeric variable scalar. 
Operand 2: Binary(2) scalar. 


Operand 3-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 
Description: The scale instruction performs numeric scaling of the source operand based on the scale 
factor and places the results in the receiver operand. The numeric operation is as follows: 
Operand 1 = Operand 2 *(B**N) 
where: 


N is the binary integer value of the scale operand. It can be positive, negative, or O. If N is 0, then 
the operation simply copies the source operand value into the receiver operand. 


B is the arithmetic base for the type of numeric value in the source operand. 
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Base Type B 
Binary 2 
Packed/Zoned 10 
Floating-point 2 


The scale operation is a shift of N binary, packed, or zoned digits. The shift is to the left if N is posi- 
tive, to the right if N is negative. For a floating-point source operand, the scale operation is performed 
as if the source operand is multiplied by a floating-point value of 2**N. 


If the source and receiver operands have different attributes, the scaling operation is done in an inter- 
mediate field with the same attributes as the source operand. If a fixed-point scaling operation causes 
nonzero digits to be truncated on the left end of the intermediate field, a size (hex OCOA) exception is 
signaled. For a floating-point scaling operation, the floating-point overflow (hex O0CO6) and the floating- 
point underflow (hex 0C07) exceptions can be signaled during the calculation of the intermediate result. 


The resultant value of the calculation is copied into the receiver operand. If this operand is not the 
same type as that used in performing the operation, the resultant value is converted to its type. If 
necessary, the resultant value is adjusted to the length of the receiver operand, aligned at the 
assumed decimal point of the receiver operand, or both before being copied to it. For fixed-point oper- 
ations, if nonzero digits are truncated off the left end of the resultant value, a size (hex OCOA) exception 
is signaled. 


For floating-point operations involving fixed-point receiver fields, if nonzero digits would be truncated 
from the left end of the resultant value, an invalid floating-point conversion (hex OCOC) exception is 
signaled. 


For floating-point receiver fields, if the exponent of the resultant value is either too large or too small to 
be represented in the receiver field, the floating-point overflow (hex O0CO6) or floating-point underflow 
(hex 0CO07) exception is signaled. 


A scalar value invalid (hex 3203) exception is signaled if the value of N is beyond the range of the 
particular type of the source operand as specified in the following table. 


Source Operand Type Maximum Value of N 
Signed Binary(2) -15<SN S15 
Unsigned Binary(2) -16$<N S16 
Signed Binary(4) -31<9N S31 
Unsigned Binary(4) -32 <N < 32 
Decimal(P,Q) -31SN $31 


For a scale operation in floating-point, no limitations are placed on the values allowed for N other than 
the implicit limits imposed due to the floating-point overflow and underflow exceptions. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 
Resultant Condition 

e Positive-The algebraic value of the receiver operand is positive. 

e Negative-The algebraic value of the receiver operand is negative. 


e Zero-The algebraic value of the receiver operand is zero. 
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e Unordered-The value assigned a floating-point receiver operand is NaN. 


Exceptions 


Exception 


06 


08 


0c 


10 


1C 


20 


22 


24 


2C 


2E 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 

02 decimal data 

06 floating-point overflow 

07 floating-point underflow 

09 floating-point invalid operand 
0A size 

OC invalid floating-point conversion 


OD floating-point inexact result 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 
08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


1 2 3 Other 


x KK XK 
x KK OK 
x KK OK 


X X X 
X 
X 
X 
X X 
X 
X. 
X 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
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Scale (SCALE) 


Operands 
Exception 1 2 3 Other 
32 Scalar specification 
03 scalar value invalid X 
36 Space management 
01 space extension/truncation xX 
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Scan (SCAN) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 
SCAN Receiver Base Compare 

10D3 operand 

SCANB Branch options Receiver Base Compare Branch targets 
1CD3 operand 

SCANI Indicator Receiver Base Compare Indicator targets 
18D3 options operand 


Operand 1: Binary variable scalar or binary array. 
Operand 2: Character variable scalar. 
Operand 3: Character scalar. 


Operand 4-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ {Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The character string value of the base operand is scanned for occurrences of the char- 
acter string value of the compare operand. 


The base and compare operands must both be character strings. The length of the compare operand 
must not be greater than that of the base string. 


The operation begins at the left end of the base string and continues character by character, from left 
to right, comparing the characters of the base string with those of the compare operand. The length of 
the comparisons are equal to the length of the compare operand value and function as if they were 
being compared in the Compare Bytes Left-Adjusted instruction. 


If a set of bytes that match the compare operand is found, the binary value for the ordinal position of 
its leftmost base string character is placed in the receiver operand. 


lf the receiver operand is a scalar, only the first occurrence of the compare operand is noted. If it is an 
array, aS many occurrences as there are elements in the array are noted. 


The operation continues until no more occurrences of the compare operand can be noted in the 
receiver operand or until the number of characters (bytes) remaining to be scanned in the base string 
is less than the length of the compare operand. 


When the second condition occurs, the receiver value is set to 0. If the receiver operand is an array, 
all its remaining elements are also set to 0. 


The base operand and the compare operand can be variable length substring compound operands. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 2 and 3. The effect of specifying a null substring reference for the compare 
operand or both operands is that the receiver is set to zero (no match found) and the instruction’s 
resultant condition is null compare operand. Specifying a null substring reference for just the base 
operand is not allowed due to the requirement that the length of the compare operand must not be 
greater than that of the base string. 
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« Zero-The numeric value(s) of the receiver operand is zero. When the receiver operand is an array, 


the resultant condition is zero if all elements are zero. One of these two conditions will result 
when the compare operand is not a null substring reference. 


Positive-The numeric value(s) of the receiver operand is positive. 


e Null compare operand-The compare operand is a null substring reference; therefore, the receiver 


Exceptions 


Exception 


06 


08 


0c 


10 


20 


22 


24 


2C 


2E 


36 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 


08 length conformance 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


has been set to zero which indicates that no occurrences were found. 


Operands 


1 2 3 Other 


X X X 
X X X 
X X X 
X X X 
X X X 

X X 


X 
X 
X 
Xx X X 
Xx X X 
X X X 
X 
x X X 
X X X 
X 
X 
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Scan (SCAN) 


Operands 
Exception 1 2 3 Other 
01 space extension/truncation X 


c 
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Scan with Control (SCANWC) 


Op Code Extender Operand 1 Operand 2 Operand 3 Operand 4 Operand [5-8] 
(Hex) 
SCANWC Base Controls Options Escape 
10E4 locator target or 
null 
SCANWCB Branch Base Controls Options Escape Branch 
1CE4 options locator target or targets 
null 
SCANWCI Indicator Base Controls Options Escape Indicator 
18E4 options locator target or targets 
null 


Operand f/f: Space pointer. 
Operand 2: Character(8) variable scalar (fixed length) 
Operand 3: Character(4) constant scalar (fixed length) 


Operand 4: Instruction number, relative instruction number, branch point, instruction pointer, instruc- 
tion definition list element, or null. 


Operand 5-8: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The base string to be scanned is specified by the base locator and controls operands. 
The base locator addresses first character of the base string. The controls specifies the length of the 
base string in the base length field. 


The scan operation begins at the left end of the base string and continues character by character, left- 
to-right. The scan operation can be performed on a base string which contains all simple (1-byte) or 
all extended (2-byte) character codes or a mixture of the two. When the base string is being inter- 
preted in simple character mode, the operation moves through the base string one byte at a time. 
When the base string is being interpreted in extended character mode, the operation moves through 
the base string 2 bytes at a time. The character string value of the base operand is scanned for occur- 
rences of a character value satisfying the criteria specified in the control and options operands. 


The scan is completed by updating the base locator and controls operands with scan status when a 
character value being scanned for is found, the end of the base string is encountered, or an escape 
code is encountered when the escape target operand is specified. The base locator is set with 
addressability to the character (simple or extended) which caused the instruction to complete exe- 
cution. The controls operand is set with information which identifies the mode (simple or extended) of 
the base string character addressed by the base locator and which provides for resumption of the scan 
operation with minimal overhead. 


The controls and options operands specify the modes to be used in interpreting characters during the 
scan operation. Characters can be interpreted in one of two character modes: simple (1-byte) and 
extended (2-byte). Additionally, the base string can be scanned in one of two scan modes, mixed 
(base string may contain a mixture of both character modes) and nonmixed (base string contains one 
mode of characters). 
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When the mixed scan mode is specified in the options operand, the base string is interpreted as con- 

taining a mixture of simple and extended character codes. The mode, simple or extended, with which 
the string is to be interpreted, is controlled initially by the base mode indicator in the controls operand 
and thereafter by mode control characters imbedded in the base string. The mode control characters 
are as follows: 


° Hex OE = Shift out (SO) of simple character mode to extended mode. 


e Hex OF = Shift in (SI) to simple character mode from extended mode. This is only recognized if it 
occurs in the first byte position of an extended character code. 


When the nonmixed scan mode is specified in the options operand, the base string is interpreted using 
only the character mode specified by the base mode indicator in the controls operand. Character 
mode shifting can not occur because no mode control characters are recognized when scanning in 
nonmixed mode. 


The base locator operand is a space pointer which is both input to and output from the instruction. On 
input, it locates the first character of the base string to be processed. On output, it locates the char- 
acter of the base string which caused the instruction to complete. 


The controls operand must be a character scalar which specifies additional information to be used to 
control the scan operation. It must be at least 8 bytes long and have the following format: 


¢ Controls operand Char(8) 
— Control indicators Char(1) 
— Reserved _ Char(1) 
-— Comparison characters Char(2) 
— Reserved Char(1) 
— Base end Char(3) 
- Instruction work area Char(1) 

- Base length Char(2) 


Only the first 8 bytes of the controls operand are used. Any excess bytes are ignored. Reserved fields 
must contain binary zeros. The control indicators field has the following format: 


¢ Control indicators Char(‘) 
— Base mode Bit O 
QO = Simple 
1 = Extended 
— Comparison character mode Bit 1 
Q = Simple 
1 = Extended 
— Reserved (must be 0) Bit 2-6 
— Scan state Bit 7 


0 = Resume scan 
1 = Start scan 


The base mode is both input to and output from the instruction. In either case, it specifies the mode of 
the character in the base string currently addressed by the base locator. 


The comparison character mode is not changed by the instruction. It specifies the mode of the com- 
parison character contained in the controls operand. 
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The scan state is both input to and output from the instruction. As input, it indicates whether the scan 
operation for the base string is being started or resumed. lf it is being started, the instruction assumes 
that the base /ength value in the base end field of the controls operand specifies the length of the base 
string, and the instruction work area value is ignored. If it is being resumed, the instruction assumes 
the base end field has been set by a prior start scan execution of the instruction with an internal! 
machine value identifying the end of the base string. 


For a start scan execution of the instruction, the scan state field is reset to indicate resume scan to 
provide for subsequent resumption of the scan operation. Additionally, for a start scan execution of the 
instruction, the base end field is set with an internally optimized value which identifies the end of the 
base string being scanned. This value then overlays the values which were in the instruction work 
area and base length fields on input to the instruction. Predictable operation of the instruction on a 
resume scan execution depends upon this base end field being left intact with the value set by the start 
scan execution. 


For a resume scan execution of the instruction, the scan state and base end fields are unchanged. 


The comparison character is input to the instruction. It specifies a character code to be used in the 
comparisons performed during the scanning of the base string. The comparison character mode in the 
control indicators specifies the mode (simple or extended) of the comparison character. If it is a 
simple character, the first byte of the comparison character field is ignored and the comparison char- 
acter is assumed to be specified in the second byte. If it is an extended character, the comparison 
character is specified as a 2-byte value in the comparison character field. 


The base end field is both input to and output from the instruction. It contains: data which identifies the 
end of the base string. Initially, for a start scan execution of the instruction, it contains the length of 
the base string in the base length field. Additionally, the base end field is used to retain information 
over multiple instruction executions which provides for minimizing the overhead required to resume 
the scan operation for a particular base string. This information is set on the initial start scan exe- 
cution of the instruction and is used during subSequent resume scan executions of the instruction to 
determine the end of the base string to be scanned. lf the end of the base string being scanned must 
be altered during iterative usage of this instruction, a start scan execution of the instruction must be 
performed to provide for correctly resetting the internally optimized value to be stored in the base end 
from the values specified in the base locator operand and base /ength field. 


For the special case of a start scan execution where a length value of Zero (no characters to scan) is 
specified in the base length field, the instruction results in a not found resultant condition. In this case, 
the base locator is not verified and the scan state indicator, the base end field, and the base locator 
are not changed. 


The options operand must be a character scalar which specifies the options to be used to control the 
scan operation. it must be at least 4 bytes in length and has the following format: 


¢ Options operand Char(4) 
— Options indicators Char(‘1) 
— Reserved Char(3) 


The options operand must be specified as a constant character scalar. 


Only the first 4 bytes of the options operand are used. Any excess bytes are ignored. Reserved fields 
must contain binary zeros. The option indicators field has the following format: 


¢ Option indicators Char(1) 
— Reserved Bit 0 
— Scan mode Bit 1 
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0 = Mixed 
1 = Nonmixed 
Cc — Reserved Bits 2-3 
— Comparison relation Bits 4-6 
- Equal, (=) relation Bit 4 
- Less than, (<) relation Bit 5 
- Greater than, (>) relation Bit 6 


0 No match on relation 
1 = Match on relation 


— Reserved Bit 7 


The scan mode specifies whether the base string contains a mixture of character modes, or contains 
all one mode of characters; that is, whether or not mode control characters should be recognized in 
the base string. Mixed specifies that there is a mixture of character modes and, therefore, mode 
control characters should be recognized. Nonmixed specifies that there is not a mixture of character 
modes and, therefore, mode control characters should not be recognized. Note that the base mode 
indicator in the controls operand specifies the character mode of the base string character addressed 
by the base locator. 


The comparison relation specifies the relation or relations of the comparison character to characters of 
the base string which will satisfy the scan operation and cause completion of the instruction with one 
of the high, low, or equal resultant conditions. Multiple relations may be specified in conjunction with 
one another. Specifying all relations insures a match against any character in the base string which is 
of the same mode as the comparison character. Specifying no relation insures a not found resultant 
condition, in the absence of an escape due to verification, regardless of the values of the characters in 
the base string which match the mode of the comparison character. 


An example of comparison scanning is a scan of simple mode characters for a value less than hex 40. 
This could be done by specifying a comparison character of hex 40 and a comparison relation of 
greater than in conjunction with a branch option for the resultant condition of high. This could also be 
done by specifying a comparison character of hex 3F and comparison relations of equal and greater 
than in conjunction with branch options for equal and high. The target of the branch options in either 
case would be the instructions to process the character less than hex 40 in value. 


The escape target operand controls the verification of bytes of the base string for values less than hex 

40. Verification, if requested, is always performed in conjunction with whatever comparison processing 
has been requested. That is, verification is performed even if no comparison relation is specified. This 
operand is discussed in more detail in the following material. 


During the scan operation, the characters of the base string which are not of the same mode as the 
comparison character are skipped over until the mode of the characters being processed is the same 
as the mode of the comparison character. The operation then proceeds by comparing the comparison 
character with each of the characters of the base string. These comparisons behave as if the charac- 
ters were being compared in the Compare Bytes Left Adjusted instruction. 


~ 


If a base string character satisfying the criteria specified in the controls and options operands is found, 
the base locator is set to address the first byte of it, the base mode indicator is set to indicate the 
mode of the base string as of that character, and the instruction is completed with the appropriate 
resultant condition based on the comparison relation (high, low, or equal) of the comparison character 
to the base string character. 
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lf a matching base string character is not found prior to encountering a mode change, the characters of 
the base string are again skipped over until the mode of the characters being processed is the same 
as the mode of the comparison character before comparisons are resumed. 


lf a matching base string character is not found prior to encountering the end of the base string, the 
base location is set to address the first byte of the character encountered at the end of the base string, 
the base mode indicator is set to indicate the mode of the base string as of that character, and the 
instruction is completed with the not found resultant condition. A mode control string results in the 
changing of the base string mode, but the base Jocator is left addressing the mode control character. 


If the escape target operand is specified (operand 4 is not null), verifications are performed on the 
characters of the base string prior to their being skipped or compared with the comparison character. 
Each byte of the base string is checked for a value less than hex 40. Additionally, for a mixed scan 
mode, when such a value is encountered, it is then determined if it is a valid mode control character. 


e Hex OE (SO) when the base string is being interpreted in simple character mode. 


¢ Hex OF (SI) in the left byte of the character code when the base string is being interpreted in 
extended character mode. 


If a byte value of less than hex 40 is not a valid mode control character, it is considered to be an 
escape code. The base locator is set to address the first byte of the base string character (simple or 
extended) which contains the escape code, the base mode indicator is set to indicate the mode of the 
base string as of that character, and a branch is taken to the target specified by the escape target 
operand. When the escape target branch is performed, the value of any optional indicator operands is 
meaningless. 


lf the escape target operand is not specified (operand 4 is null), verifications of the character codes in 
the base string are not performed. However, for a mixed scan mode, mode control values are always 
processed as described previously under the discussion of the mixed scan mode. 


If possible, use a Space Pointer Machine Object for the base locator, operand 1. Appreciably less 
overhead is incurred in accessing and storing the value of the base locator if this is done. 


If possible, specify through its ODT definition, the controls operand on an 8-byte multiple (doubleword) 
boundary relative to the start of the space containing it. Appreciably less overhead is incurred in 
accessing and storing the value of the controls if this is done. 


For the case where a base string is to be just scanned for byte values less than hex 40, two techniques 
can be used. 


¢« A direct simple mode scan for a value less than hex 40 without usage of the escape target verifica- 
tion feature. 


¢« A scan for any character with usage of the escape target verification feature. 


The direct scan approach, the former, is the more efficient. 


The following diagram defines the various conditions which can be encountered at the end of the base 
string and what the base locator addressability is in each case. The solid vertical line represents the 
end of the base string. The dashes represent the bytes before and after the base string end. The V is 
positioned over the byte addressed by the base locator in each case. These are the conditions which 
can be encountered when the base locator input to the instruction addresses a byte prior to the base 
string end. When the base length field specifies a value of zero for a start scan execution of the 
instruction, or the input base locator addresses a point beyond the end of the instruction, no proc- 
essing is performed and the instruction is immediately completed with the not found resultant condi- 
tion. 
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Addressability Ending Condition Instruction Response 
V ‘(One byte code at string enc) 
° Simple character e Appropriate resultant 


= condition Indicating 
found or not found 


° Shift Infout encountered * Mode shift performed, 
and not found resultant 
condition 

e Escape code In simple e Branch taken 

character 
V (Extended character split 
across string end) 
* Extended character » Not found resultant 
a condition 
* Escape code In extended e Branch taken 
character 
V (Extended character at 
string end) 
* Extended character ° Appropriate resultant 
—= condition indicating — 
found or not found 
*® Escape code In extended » Branch taken 
character 
AACOT2-0 


An analysis of the diagram shows that normaily, after appropriate processing for the particular found, 
not found, or escape condition, the scan can be restarted at the byte of data which would follow the 
base string end in the data stream being scanned. Any mode shift required by an ending mode control 
character will have been performed. 


However, one ending condition may require subsequent resumption of the scan at the character 
encountered at the end of the base string. This is the case where the instruction completes with the 
not found resultant condition and the base string ends with an extended character split across string 
end. That is, the base mode indicator specifies extended mode, the base locator addresses the last 
byte of the base string, and that byte value is not a shift out, hex OE character. In this case, complete 
verification of the extended character and relation comparison could not be performed. If this 
extended character is to be processed, it must be done through another execution of the Scan instruc- 
tion where both bytes of the character can be input to the instruction within the confines of the base 
string. 


Resultant Conditions 


e Equal: A character value was found in the base string which satisfies the criteria specified in the 
controls and options operands in that the comparison character is of equal string value to the base 
string character. 


e High: A character value was found in the base string which satisfies the criteria specified in the 
controls and options operands in that the comparison character is of higher string value to the 
base string character. 
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e Low: A character value was found in the base string which satisfies the criteria specified in the 


controls and options operands in that the comparison character is of lower string value to the base 
string character. ° 


e Not found: A character value was not found in the base string which satisfied the criteria specified 


in the controls and options operands. 


Exceptions 


Exception 


06 


08 


oc 


10 


20 


22 


24 


2C 


2E 


32 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 


08 length conformance 


Damage encountered ._ 
04 System object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 


03 scalar value invalid 


Operands 


x KK XK 


x 


2 3 4 Other 


X X X 

X X X 

X X X 

X X X 

X X X 

X X 
X 
X 
Xx 
X 
X 

X X X 

X X X 

X X X 
X 

X X X 

X X X 
X 
X 

X X X 

X X 


Chapter 2. Computation and Branching Instructions 2-207 


J 


f ene 


Scan with Control (SCANWC) 


Operands 
Exception 1 2 3 4 Other 
36 Space management 
01 space extension/truncation X 
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Op Code Extender Operand 1 Operand 2 Operand 3 Operand 4 Operand [5-6] - 
(Hex) 

SEARCH Receiver Array Find Location 

1084 

SEARCHB Branch Receiver Array Find Location Branch 

1C84 options targets 

SEARCHI Indicator Receiver Array Find Location Indicator 

1884 options targets 


Operand 1: Binary variable scalar or binary variable array. 
Operand 2: Character array or numeric array. 

Operand 3: Character variable scalar or numeric variable scalar. 
Operand 4: Binary scalar. 


Operand 5-6: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


per ., 


Description: The portions of the array operand indicated by the location operand are searched for 
occurrences of the value indicated in the find operand. wa 


The operation begins with the first element of the array operand and continues element by element, 
comparing those characters of each element (beginning with the character indicated in the location 
operand) with the characters of the find operand. The location operand contains an integer value 
representing the relative location of the first character in each element to be used to begin the 
compare. 


The integer value of the location operand must range from 1 to L, where L is the length of the array 
operand elements; otherwise, a scalar value invalid (hex 3203) exception is signaled. A value of 1 indi- 
cates the leftmost character of each element. 


The array and find operands can be either character or numeric. Any numeric operands are inter- 
preted as logical character strings. The compares between these operands are performed at the 
length of the find operand and function as if they were being compared in the Compare Bytes Left- 
Adjusted instruction. 


The length of the find operand must not be so large that it exceeds the length of the array operand 
elements when used with the location operand value. The array element length used is the length of 
the array scalar elements and not the length of the entire array element, which can be larger in non- 
contiguous arrays. 


As each occurrence of the find value is encountered, the integer value of the index for this array 

element is placed in the receiver operand. If the receiver operand is a scalar, only the first element 

containing the find value is noted. If the receiver operand is an array, as many occurrences as there 

are elements within the receiver array are noted. 2 | 
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lf the value of the index for an array element containing an occurrence of the find value is too large to 
be contained in the receiver, a size (hex OCOA) exception is signaled. 


The operation continues until no more occurrences of elements containing the find value can be noted 
in the receiver operand or until the array operand has been completely searched. When the second 
condition occurs, the receiver value is set to LB-1, where LB is the value of the lower bound index of 
the array. If LB is the most negative 32-bit integer, then LB-1 is the most positive 32-bit integer; other- 
wise, LB-1 is 1 less than LB. If the receiver operand is an array, all its remaining elements are also 
set to LB-1. The find operand can be a variable length substring compound operand. 


Resultant Conditions :: The numeric value(s) of the receiver operand is either LB-1 or in the range LB 
through UB, where UB is the value of the upper bound index of the array. When the receiver is LB-1, 
the resultant condition is zero. When the receiver is in the range LB through UB, the resultant condi- 
tion is positive. When the receiver is an array, the resultant condition is zero if all elements are LB-1; 
otherwise, it is positive. The resultant condition is unpredictable when the no binary size exception 
program template option is used. 


Exceptions 


Exception 


06 


08 


oc 


20 


22 


24 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computation 
08 length conformance 


0A size 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 abject destroyed 
03 object suspended 


08 object compressed 


Pointer specification 


01 pointer does not exist 


Operands 


1 2 3 4 Other 


x x x x 
x «x x x 
x x x x 
x x * x 


X 
X 
X 
X X X X 
X X X X 
X X X X 
X 


X X X X 
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02 pointer type invalid 
2C Program execution 


04 invalid branch target 


2E Resource control limit 


01 user profile storage limit exceeded 


32 Scalar specification 
01 scalar type invalid 


03 scalar value invalid 


36 Space management 


01 space extension/truncation 


Search (SEARCH) 


Operands 
1 2 3 4 Other 
Xx X X X 


X 

X 
X X X X 
X 

X 
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Set Bit in String (SETBTS) 


Op Code (Hex) Operand 1 Operand 2 
101E Source Offset 


Operand 1: Character variable scalar (fixed length) or numeric variable scalar. 
Operand 2: Binary scalar. 

Description: Sets the bit of the receiver operand as indicated by the bit offset operand. 
The selected bit from the receiver operand is set to a value of binary 1. 


The receiver operand can be a character or numeric variable. The leftmost bytes of the receiver 
Operand are used in the operation. The receiver operand is interpreted as a bit string with the bits 
numbered left to right from 0 to the total number of bits in the string minus 1. 


The offset operand indicates which bit of the receiver operand is to be set, with a offset of zero indi- 
cating the leftmost bit of the leftmost byte of the receiver operand. This value may be specified as a 
constant or any valid binary scalar variable. 


If a offset vaiue less than zero or beyond the length of the receiver is specified a scalar value invalid 
(hex 3203) exception is signaled. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 Spacing addressing violation 

02 Boundary alignment violation 

03 Range 

06 Optimized addressability invalid 


x KK XK 
x KK XK 


08 Argument/parameter 


01 Parameter reference violation Xx D4 


10 Damage encountered 
04 System object damage state X 
44 Partial system object damage. X 


1c Machine-dependent exception 
03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check 4 
03 Function check Xx 


22 Object access 
02 Object destroyed X Xx 
03 Object suspended X X 
08 object compressed X 
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Exception 
24 Pointer specification 


01 Pointer does not exist 


02 Pointer type invalid 


2E Resource control limit 


01 user profile storage limit exceeded 


32 Scalar specification 
01 Scalar type invalid 


03 Scalar value invalid 


36 Space management 


01 space extension/truncation 


Set Bit in String (SETBTS) 


Operands 


1 2 Other 


X X 
X X 
X 
X X 
X 
X 
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Set Instruction Pointer (SETIP) 


Op Code (Hex) Operand 1 Operand 2 
1022 Receiver Branch target 


Operand ?: Instruction pointer. 
Operand 2: Instruction number, relative instruction number, or branch point. 


Description: The value of the branch target (operand 2) is used to set the value of the instruction 
pointer specified by operand 1. The instruction number indicated by the branch target must provide 
the address of an instruction within the program containing the Set Instruction Pointer instruction. 


Exceptions 


Exception 1 2 Other 
06 Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x KK XK 


08 Argument/parameter 


01 parameter reference violation X 


10 Damage encountered 
04 system object damage state X X xX 
44 partial system object damage xX xX X 


1C Machine-dependent exception 


03 machine storage limit exceeded x 


20 Machine support 
02 machine check Xx 
03 function check X 


22 Object access 
01 object not found X 
02 object destroyed 
03 object suspended X 


x 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X 


02 pointer type invalid X 


2C Program execution 


04 branch target invalid xX 


2E Resource control limit 


01 user profile storage limit exceeded X 
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Operands 
Exception 1 2 Other 
36 Space management 
01 space extension/truncation X 2 


Chapter 2. Computation and Branching Instructions 2-215 


c 


Store and Set Computational Attributes (SSCA) 


Store and Set Computational Attributes (SSCA) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
1078 Receiver Source Controls 


Operand 1: Character(5) variable scalar (fixed length). 
Operand 2: Character(5) scalar (fixed length) or null. 


Operand 3: Character(5) scalar (fixed length) or null. 


Description: This instruction stores and optionally sets the attributes for controlling computational 


operations for the process this instruction is executed in. 


The receiver is assigned the values that each of the computational attributes had at the start of exe- 
cution of the instruction. It has the same format and bit assignment as the source. 


The source specifies new values for the computational attributes for the process. The particular com- 
putational attributes that are selected for modification are determined by the controls operand. The 


source operand has the following format: 
¢ Floating-point exception masks 


0 = Disabled (exception is masked) 
1 = Enabled (exception is unmasked) 


— Reserved (binary 0) 
— Floating-point overflow 
— Floating-point underflow 
— Floating-point zero divide 
— Floating-point inexact result 
— Floating-point invalid operand 
— Reserved (binary 0) 
¢ Floating-point exception occurrence flags 


0 = Exception has not occurred 
1 = Exception has occurred 


— Reserved (binary 0) 

— Floating-point overflow 

— Floating-point underflow 

— Floating-point zero divide 

— Floating-point inexact result 
— Floating-point invalid operand 


— Reserved (binary 0) 


e Modes 
— Reserved 
— Floating-point rounding mode 


00= Round toward positive infinity 
01= Round toward negative infinity 


Char(2) 


"Bits 0-9 


Bit 10 
Bit 11 
Bit 12 
Bit 13 
Bit 14 
Bit 15 
Char(2) 


Bits 0-9 

Bit 10 

Bit 11 

Bit 12 

Bit 13 

Bit 14 . 
Bit 15 


Char(1) 
Bit O 
Bits 1-2 
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10= Round toward zero 
11= Round to nearest (default) 


— Reserved Bits 3-7 


The controls operand is used to select those attributes that are to be set from the bit values of the 
source operand. The format of the controls is the same as that for the source. A value of one for a bit 
in controls indicates that the corresponding computational! attribute for the process is to be set from 
the value of that bit of the source. A value of zero for a bit in controls indicates that the corresponding 
computational attribute for the process is not to be changed, and will retain the value it had prior to 
this instruction. For an attribute controlled by a multiple-bit field, such as the rounding modes, all of 
the bits in the field must be ones or all must be zeros. A mixture of ones and zeros in such a field 
results in a scalar value invalid (hex 3801) exception. 


If the source and controls operands are both null, the instruction will just return the current computa- 
tional attributes. If the source is specified, the computational attributes of the process are modified 
under control of the controls operand. If the source operand is specified and the controls operand is 
null, the instruction will change all of the computational attributes to the values specified in the source. 
If the source operand is null and the controls operand is specified, an invalid operand type (hex 2A06) 
exception is signaled on the Create Program instruction. 


With the floating-point exception masks field, it is possible to unmask/mask the exception processing 
and handling for each of the five floating-point exceptions. If an exception that is unmasked occurs, 
then the corresponding floating point exception occurrence bit is set, and the exception is signaled. If 
an exception that is masked occurs, the exception is not signaled, but the floating pointer exception 
occurrence flag is still set to indicate the occurrence of the exception. | 


The floating-point exception occurrence flag for each exception may be set or cleared by this instruc- 
tion from the source operand under control of the controls operand. 


Unless specified otherwise by a particular instruction, or precluded due to implicit conversions, all 
floating-point operations are performed as if correct to infinite precision, and then rounded to fit in a 
destinations format while potentially signaling an exception that the result is inexact. To allow control 
of the floating-point rounding operations performed within a process, four floating-point rounding 
modes are supported. Assume y is the infinitely precise number that is to be rounded, bracketed most 
closely by x and z, where x is the largest representable value less than y and z is the smallest repre- 
sentable value greater than y. Note that x or z may be infinity. The following diagram shows this 
relationship of x, y, and Z on a scale of numerically progressing values where the vertical bars denote 
values representable in a floating-point format. 


Xx Y Z 


Smaller < oe oe oe ee > Larger 


AACOT-O 


Given the above, if y is not exactly representable in the receiving field format, the rounding modes 
change y as follows: - 


Round to nearest with round to even in case of a tie is the default rounding mode in effect upon the 
initiation of a process. For this rounding mode, y is rounded to the closer of x or z. If they are equally 
close, the even one (the one whose least significant bit is a zero) is chosen. For the purposes of this 
mode of rounding, infinity is treated as if it was even. Except for the case of y being rounded to a 
value of infinity, the rounded result will differ from the infinitely precise result by at most half of the 
least significant digit position of the chosen value. This rounding mode differs slightly from the decimal 
round algorithm performed for the optional round form of an instruction. This rounding mode would 
round a value of 0.5 to 0, where the decimal round algorithm would round that value to 1. 
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Round toward positive infinity indicates directed rounding upward is to occur. For this mode, y is 
rounded to Z. 


Round toward negative infinity indicates directed rounding downward is to occur. For this mode, y is 
rounded to x. 


Round toward zero indicates truncation is to occur. For this mode, y is rounded to the smaller (in 
magnitude) of x or Z. 


Arithmetic operations upon infinity are exact. Negative infinity is less than every finite value, which is 
less than positive infinity. 


The computational attributes are set with a default value upon process initiation. The default attributes 
are as follows: 


e The floating-point inexact result exception is masked. The other floating-point exceptions are 
unmasked. 


e All floating point occurrence bits have a zero value. 
e Round to the nearest rounding mode. 


These attributes can be modified by a program executing this instruction. The new attributes are then 
in effect for the program executing this instruction and for programs invoked subsequent to it unless 
changed through another execution of this instruction. External exception handlers and invocation exit 
routines are invoked with the same attributes as were last in effect for the program invocation they are 
related to. Event handlers do not really relate to another invocation in the process. As such, they are 
invoked with the attributes that were in effect at the point the process was interrupted to handle the 
event. 


Upon return to the invocation of a program from subsequent program invocations, the computational 
attributes, other than floating point exception occurrence attributes, are restored to those that were in 
effect when the program gave up control. The floating point exception occurrence attributes are left 
intact reflecting the occurrence of any floating-point exceptions during the execution of subsequent 
invocations. 


Internal exception handlers execute under the invocation of the program containing them. As such, the 
above discussion of how computational attributes are restored upon returning from an external excep- 
tion handler does not apply. The execution of an internal exception handler occurs in a manner similar 
to the execution of an internal subroutine invoked through the Call Internal instruction. If the internal 
exception handler modifies the attributes, the modification remains in effect for that invocation when 
the exception handler completes the exception. 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 space addressing violation X X X 

02 boundary alignment X X X 

03 range X X X 

06 optimized addressability invalid X X X 
08 Argument/parameter 

01 parameter reference violation X X X 
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Exception 


10 


1C 


20 


22 


24 


2E 


32 


36 


Damage encountered 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Store and Set Computational Attributes (SSCA) 


Operands 


1 2 3 Other 


X 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X X 
X X 
X 
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Subtract Logical Character (SUBLC) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-6] 
SUBLC Difference Minuend Subtrahend 

1027 

SUBLCI Indicator Difference Minuend Subtrahend Indicator targets 
1827 options 

SUBLCB Branch options Difference Minuend Subtrahend Branch targets 
1C27 


Operand 1: Character variable scalar (fixed-length). 
Operand 2: Character scalar (fixed-length). 
Operand 3: Character scalar (fixed-length). 


Operand 4-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


« Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-5] 
SUBLCS Difference/Minuend Subtrahend 

1127 

SUBLCIS Indicator options Difference/Minuend Subtrahend Indicator targets 
1927 

SUBLCBS Branch options Difference/Minuend Subtrahend Branch targets 
1D27 


Operand 1: Character variable scalar (fixed-length). 
Operand 2: Character scalar (fixed-length). 


Operand 3-5: 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ /ndicator Form-Numeric variable scalar or character variable scalar. 


Description: The unsigned binary value of the subtrahend operand is subtracted from the unsigned 
binary value of the minuend operand, and the result is placed in the difference operand. 


Operands 1, 2, and 3 must be the same length; otherwise, the Create Program instruction signals an 
invalid length (hex 2A0A) exception. 


The subtraction operation is performed as though the ones complement of the second operand and a 
low-order 1-bit were added to the first operand. 
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The result value is then placed (left-adjusted) into the receiver operand with truncating or padding 
taking place on the right. The pad value used in this instruction is a byte value of hex 00. 


If operands overlap but do not share all of the same bytes, results of operations performed on these J 
operands are not predictable. If overlapped operands share all of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 
Resultant Conditions: The logical difference of the character scalar operands is: 
e Zero with carry out of the high-order bit position 
e Not-zero with carry 


¢ Not-zero with no carry. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x KK OK 
x KK KK 
x K KK 


08 Argument/Parameter 
01 Parameter reference violation X X X :) 


10 Damage Encountered 
04 System object damage state X X X X 
44 Partial system object damage X xX xX X 


1C Machine-Dependent Exception 
03 Machine storage limit exceeded Xx 


20 Machine Support 
02 Machine check xX 
03 Function check xX 


22 Object Access 
01 Object not found X Xx X 
02 Object destroyed 
03 Object suspended X X X 
08 object compressed X 


< 
x 
x 


24 Pointer Specification 
01 Pointer does not exist X X X 
02 Pointer type invalid X X X 


2C Program Execution ; 
04 Invalid branch target X J 


2E Resource Control Limit 
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01 User Profile storage limit exceeded 
32 Scalar Specification 

01 Scalar type invalid 


02 Scalar attributes invalid 


36 Space Management 


01 Space Extension/Truncation 


Subtract Logical Character (SUBLC) 


Operands 

1 2 3 Other 
X 

X X X 

X X X 
X 
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Subtract Numeric (SUBN) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-7] 
SUBN Difference Minuend Subtrahend 

1047 

SUBNR Difference Minuend Subtrahend 

1247 

SUBNB Branch options Difference Minuend Subtrahend Branch targets 
1C47 

SUBNBR Branch options Difference Minuend Subtrahend Branch targets 
1E47 

SUBNI Indicator Difference Minuend Subtrahend Indicator targets 
1847 options 

SUBNIR Indicator Difference Minuend Subtrahend Indicator targets 
1A47 options 


Operand 1: Numeric variable scalar. 
Operand 2: Numeric scalar. 


Operand 3: Numeric scalar. 


pte 
# , 


Operand 4-7: } 
e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Short forms 

Op Code (Hex) Extender Operand 1 Operand 2 Operand [3-6] 
SUBNS Difference/Minuend Subtrahend 

1147 

SUBNSR Difference/Minuend Subtrahend 

1347 

SUBNBS Branch options Difference/Minuend Subtrahend Branch targets 
1D47 

SUBNBSR Branch options Difference/Minuend Subtrahend Branch targets 
1F47 . 
SUBNIS Indicator options Difference/Minuend Subtrahend Indicator targets 
1947 

SUBNISR Indicator options Difference/Minuend Subtrahend Indicator targets 


Operand 71: Numeric variable scalar. 
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Operand 2: Numeric scalar. 


Operand 3-6: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 
Description: The Difference is the result of subtracting the Subtrahend from the Minuend. 
Operands can have floating-point, packed or zoned decimal, signed or unsigned binary type. 
Source operands are the Minuend and Subtrahend. The receiver operand is the Difference. 


lf operands have different types, source operands, Minuend and Subtrahend, are converted according 
to the following rules: 


1. If any one of the operands has floating point type, source operands are converted to floating point 
type. 


2. Otherwise, if any one of the operands has zoned or packed decimal type, source operands are 
converted to packed decimal. 


3. Otherwise, the binary operands are converted to a like type. Note: unsigned binary(2) scalars are 
logically treated as signed binary(4) scalars. 


Minuend and Subtrahend are subtracted according to their type. Floating paint operands are sub- 
tracted using floating point subtraction. Packed decimal operands are subtracted using packed 
decimal subtraction. Unsigned binary subtraction is used with unsigned binary operands. Signed 
binary operands are subtracted using two’s complement binary subtraction. 


Better performance can be obtained if all operands have the same type. Signed and unsigned binary 
subtractions execute faster than either packed decimal or floating point subtractions. 


Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. 


For a decimal operation, alignment of the assumed decimal point takes place by padding with O’s on 
the right end of the source operand with lesser precision. 


Floating-point subtraction uses exponent comparison and significand subtraction. Alignment of the 
binary point is performed, if necessary, by shifting the significand of the value with the smaller expo- 
nent to the right. The exponent is increased by one for each binary digit shifted until the two expo- 
nents agree. 


The operation uses the length and the precision of the source and receiver operands to calculate accu- 
rate results. Operations performed in decimal are limited to 31 decimal digits in the intermediate 
result. 


The subtract operation is performed according to the rules of algebra. 


The result of the operation is copied into the difference operand. If this operand is not the same type 
as that used in performing the operation, the resultant value is converted to its type. If necessary, the 
resultant value is adjusted to the length of the difference operand, aligned at the assumed decimal 
point of the difference operand, or both before being copied to it. For fixed-point operation, if signif- 
icant digits are truncated on the left end of the resultant value, a size (hex OCOA) exception is signaled. 


For the optional round form of the instruction, specification of a floating-point receiver operand is 
invalid. 


Chapter 2. Computation and Branching Instructions 2-224 


subtract Numeric (SUBN) 


For floating-point operations involving a fixed-point receiver field, if nonzero digits would be truncated 
off the left end of the resultant value, an invalid floating-point conversion (nex OCOC) exception is sig- 


naled. 
J 


For a floating-point difference operand, if the exponent of the resultant value is either too Jarge or too 
small to be represented in the difference field, the floating-point overflow (hex O0CO6) or the floating- 
point underflow (hex 0C07) exception is signaled. 


If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value 
contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- 
tional digits. 


Size exceptions can be inhibited. 
Limitations: The following are limits that apply to the functions performed by this instruction. 


If operands overlap but do not share alli of the same bytes, results of operations performed on these 
operands are not predictable. If overlapped operands share all of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


Resultant Conditions 
¢ Positive-The algebraic value of the numeric scalar difference is positive. 


e Negative-The algebraic value of the numeric scalar difference is negative. 


e Zero-The algebraic value of the numeric scalar difference is zero. 


4p. 


e Unordered-The value assigned a floating-point difference operand is NaN. 3 
Exceptions 
Operands 
Exception 1 2 3 (4, 5] Other 
06 Addressing 


01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x K K RK 
x KX K XK 
x K K K 


08 Argument/Parameter 


01 Parameter reference violation D4 D4 Xx 


0c Computation 
02 Decimal data X X 
03 Decimal point alignment X X 
06 Floating-point overflow X 
07 Floating-point underflow X 
09 Floating-point invalid operand X X X 
0A Size X 


OC Invalid floating-point conversion 


u. 


OD Floating-point inexact result X 
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Exception 


10 


1C 


20 


22 


24 


2C 


2E 


36 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine-Dependent Exception 


03 Machine storage limit exceeded 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Program Execution 


04 Invalid branch target 


Resource Control Limit 


01 User Profile storage limit exceeded 


Space Management 


01 Space Extension/Truncation 


Subtract Numeric (SUBN) 


Operands 


1 2 3 [4,5] Other 


X X X X 
X X X X 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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Test and Replace Characters (TSTRPLC) 


Op Code (Hex) Operand 1 


10A2 


Receiver 


Operand 1: Character variable scalar. 


Operand 2: Character scalar. 


Operand 2 
Replacement 


Description: The character string value represented by operand 1 is tested byte by byte from left to 
right. Any byte to the left of the leftmost byte which has a value in the range of hex F1 to hex F9 is 


assigned a byte value equal to the leftmost byte of operand 2. Both operands must be character 


strings. Only the first character of the replacement string is used in the operation. 


The operation stops when the first nonzero Zoned decimai digit is found or when all characters of the 
receiver operand have been replaced. 


Exceptions 


Exception 


06 


08 


10 


1C 


20 


22 


24 


2E 


Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine-Dependent Exception 


03 Machine storage limit exceeded 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


Operands 


1 2 Other 


X X 

X X 

X X 

X X 

X X 

X X X 

X X X 
X 
X 
X 

X X 

X X 

X X 
X 

X X 

X X 
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Test and Replace Characters (TSTRPLC) 


Operands 
Exception 1 2 Other 
01 User Profile storage limit exceeded X 
c 36 Space Management 
01 Space Extension/Truncation X 
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Test Bit in String (TSTBTS) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 [4] J 
TSTBTSB Branch options Source Offset Branch targets 

1COE 

TSTBTSI Indicator options Source Offset Indicator targets 

180E 


Operand 1: Character scalar (fixed length) or numeric scalar. 
Operand 2: Binary scalar. 


Operand 3: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 
Description: Tests the bit of the source operand as indicated by the offset operand to determine if the 
bit is set or not set. 
Based on the test, the resulting condition is used with the extender field to either 


e Transfer control conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


e Assign a value to each of the indicator operands (indicator form). t 
The source operand can be character or numeric. The leftmost bytes of the source operand are used J 


in the operation. The source operand is interpreted as a bit string with the bits numbered left to right 
from QO to the total number of bits in the string minus one. 


The offset operand indicates which bit of the source operand is to be tested, with a offset of zero indi- 
cating the leftmost bit of the leftmost byte of the source operand. 


If an offset value less than zero or beyond the length of the string is specified a scalar value invalid 
(hex 3203) exception is signaled. 
Resultant Conditions 

*« Zero: The selected bit of the bit string source operand is Zero. 


* One: The selected bit of the bit string source operand is one. 


Exceptions 
Operands 

Exception 1 2 3 [4] Other 
06 Addressing 

01 Spacing addressing violation xX X X 

02 Boundary alignment violation X X X 

03 Range X X X 

06 Optimized addressability invalid X X X e | 
08 Argument/parameter | 
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Exception 


10 


1C 


20 


22 


24 


2E 


32 


36 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


03 Scalar value invalid 


Space management 


01 space extension/truncation 


Test Bit in String (TSTBTS) 


Operands 
1 2 3 [4] Other 
X X X 
X 
X 
X 
X 
X 
X X X 
X X X 
X 
X X X 
X X xX 
X 
X X X 
X 
X 
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Test Bits Under Mask (TSTBUM) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 (4, 5] 
TSTBUMB Branch options Source Mask Branch targets 
1C2A 

TSTBUMI Indicator options Source Mask Indicator targets 
182A 


Operand 7: Character variable scalar or numeric variable scalar. 
Operand 2: Character scalar or numeric scalar. 
Operand 3 [4, 5] 


e Branch Form-instruction number, relative instruction number, branch point, or instruction pointer. 


e /ndicator Form-Numeric variable scalar or character variable scalar. 


Description: Selected bits from the leftmost byte of the source operand are tested to determine their 
bit values. 


Based on the test, the resulting condition is used with the extender field to: 


¢ Transfer control conditionally to the instruction indicated in one of the branch target operands 
(branch form). 


e Assign a value to each of the indicator operands (indicator form). 


The source and the mask operands can be character or numeric. The leftmost byte of each of the 
operands is used in the operands. The operands are interpreted as bit strings. The testing is per- 
formed bit by bit with only those bits indicated by the mask operand being tested. A 1-bit in the mask 
operand specifies that the corresponding bit in the source value is to be tested. A 0-bit in the mask 
operand specifies that the corresponding bit in the source value is to be ignored. 


Resultant Conditions: The selected bits of the bit string source operand are all zeros, all ones, or 
mixed ones and zeros. A mask operand of all zeros causes a zero resultant condition. 


Exceptions 

Operands 
Exception 1 2 3 [4,5] Other 
06 Addressing 


01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x K~ K K 
x KK XK 
x KX K XK 


08 Argument/parameter 
01 parameter reference violation X X X 
10 Damage encountered 
04 system object damage state X X X X 
44 partial system object damage X X X Xx 
1C Machine-dependent exception 
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Exception 


20 


22 


24 


2C 


2E 


36 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 branch target invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Test Bits Under Mask (TSTBUM) 


Operands 
1 2 3 [4, 5] Other 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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Translate (XLATE) 


Translate (XLATE) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 - 
1094 Receiver Source Position Replacement 


Operand 7: Character variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character scalar or null. 
Operand 4: Character scalar. 


Description: Selected characters in the string value of the source operand are translated into a dif- 
ferent encoding and placed in the receiver operand. The characters selected for translation and the 
character values they are translated to are indicated by entries in the position and replacement 
strings. All the operands must be character strings. The source and receiver values must be of the 
same length. The position and replacement operands can differ in length. If operand 3 is null, a 
256-character string is used, ranging in value from hex 00 to hex FF (EBCDIC collating sequence). 


The operation begins with all the operands left-adjusted and proceeds character by character, from left 
to right until the character string value of the receiver operand is completed. 


Each character of the source operand value is compared with the individual characters in the position 
operand. If a character of equal value does not exist in the position string, the source character is 
placed unchanged in the receiver operand. If a character of equal value is found in the position string, 


the corresponding character in the same relative location within the replacement string is placed in the _ 
receiver operand as the source character translated value. If the replacement string is shorter than ‘ 
the position string and a match of a source to position string character occurs for which there is no 2 


corresponding replacement character, the source character is placed unchanged in the receiver 
Operand. lf the replacement string is longer than the position string, the rightmost excess characters 
of the replacement string are not used in the translation operation because they have no corre- 
sponding position string characters. If a character in the position string is duplicated, the first occur- 
rence (leftmost) is used. 


lf operands overlap but do not share all of the same bytes, results of operations performed on these 
operands are not predictable. If overlapped operands share ail of the same bytes, the results are pre- 
dictable when direct addressing is used. If indirect addressing is used (that is, based operands, 
parameters, strings with variable lengths, and arrays with variable subscripts), the results are not 
always predictable. 


The receiver, source, position, and replacement operands can be variable length substring compound 
operands. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for all of the operands on this instruction. The effect of specifying a null substring reference 
for either the position or replacement operands is that the source operand is copied to the receiver 
with no change in value. The effect of specifying a null substring reference for both the receiver and 
the source operands (they must have the same length) is that no result is set. 


Exceptions 


Operands ~ 
Exception 1 2 3 4 Other a 


06 Addressing 
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Exception 


08 


OC 


10 


1C 


20 


22 


24 


2E 


36 


01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invatid 


Argument/Parameter 


01 Parameter reference violation 


Computation 


08 Length conformance 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine-Dependent Exception 


03 Machine storage limit exceeded 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


01 User Profile storage limit exceeded 


Space Management 


01 Space Extension/Truncation 


Translate (XLATE) 


Operands 


x KX K KW 
x K KX KS 


X 
X 
X 
X X X X 
X X X X 
X X X X 
X 
X X X X 
X X X X 
X 
X 
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Translate with Table (KLATEWT) 


Translate with Table (XLATEWT) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
109F Receiver Source Table 


Operand f: Character variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character scalar. 


Description: The source characters are translated under control of the translate table and placed in 
the receiver. The operation begins with the leftmost character of operand 2 and proceeds character- 
by-character, left-to-right. 


Characters are translated as follows: 


e The source character is used as an offset and added to the location of operand 3. 


e The character contained in the offset location is the translated character. This character is copied 
to the receiver in the same relative position as the original character in the source string. 


If operand 3 is less than 256 bytes long, the character in the source may specify an offset beyond the 
end of operand 3. If operand 2 is longer than operand 1, then only the leftmost portion of operand 2, 
equal to the length of operand 1, is translated. If operand 2 is shorter than operand 1, then only the 

leftmost portion of operand 1, equal to the length of operand 2, is changed. The remaining portion of 
operand 1 is unchanged. 


If operand 1 overlaps with operand 2 and/or 3, the overlapped operands are updated for every char- 
acter translated. The operation proceeds from left to right, one character at a time. The following 
example shows the results of an overlapped operands translate operation. Operands 1, 2, and 3 have 
the same coincident character string with a value of hex 050403020103. 


Hex 050403020103-Initial value 

Hex 030403020103-After the 1st character is translated 
Hex 030103020103-After the 2nd character is translated 
Hex 030102020103-After the 3rd character is translated 
Hex 030102020103-After the 4th character is translated 
Hex 030102020103-After the 5th character is translated 
Hex 030102020102-After the 6th character, the final result 


Note that the instruction does not use the length specified for the table operand to constrain access of 
the bytes addressed by the table operand. 


If operand 3 is less than 256 characters long, and a source character specifies an offset beyond the 
end of operand 3, the result characters are obtained from byte locations in the space following operand 
3. If that portion of the space is not currently allocated, a space addressing exception is signaled. If 
operand 3 is a constant with a length less than 256, source characters specifying offsets greater than 
or equal to the length of the constant are translated into unpredictable characters. 


All of the operands support variable length substring compound scalars. 
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Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for all of the operands on this instruction. Specifying a null substring reference for the table 
operand does not affect the operation of the instruction. In this case, the bytes addressed by the table 


operand are still accessed as described above. This is due to the definition of the function of this 


instruction which does not use the length specified for the table operand to constrain access of the 
bytes addressed by the table operand. The effect of specifying a null substring reference for either or 
both of the receiver and the source operands is that no result is set. 


Exceptions 


Exception 


06 


08 


10 


1c 


20 


22 


24 


2E 


32 


36 


Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Damage Encountered 


44 Partial system object damage 


Machine-Dependent Exception 
03 Machine storage limit exceeded 


Machine Support 
02 Machine check 


03 Function check 


Object Access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


01 User Profile storage limit exceeded 


Scalar Specification 


01 Scalar type invalid 


Space Management 


01 Space Extension/Truncation 


1 2 3 Other 


X X X 
X X X 
X X X 
Xx X X 
X X X 
X 
X 
X 
X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X X X 
X 
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Translate with Table and DBCS Skip (XLATWTDS) 


Translate with Table and DBCS Skip (XLATWTDS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
1077 Target Length Table 


Operand f: Character variable scalar (fixed length). 
Operand 2: Binary(4) scalar. 


Operand 3: Character scalar (fixed length). 


ILE access 


XLATWTDS ( 
var target : aggregate; 
var length : unsigned binary; 
var table : aggregate 


) 


Description: The simple (single byte) characters in the Target are translated under control of the 
translate table, for the length defined by Operand 2. The extended (double byte) character portions of 
the target are bypassed and not translated. The operation begins with the leftmost character of 
operand 1 and proceeds character-by-character, left-to-right, skipping over any Double byte character 
(DBCS) data portions. 


The target, Operand 1, should have double byte character data surrounded by a shift out control char- 
acter (SO = hex QE) and a shift in control character (SI= hex OF). Once a SO character is encount- 
ered, the translating of single byte characters halts. The operation will then proceed double byte 
character-by-double byte character until a S! character is encountered. This shift in character is then 
used to restart the translating of single byte characters. 


The length operand, Operand 2, is the number of bytes and must contain a value between 1 and 32767. 
For length values outside this range a scalar value invalid (hex 3203) exception is signaled. 


Single byte characters are translated as follows: 
e The target character is used as an offset and added to the location of Operand 3. 


e The character contained at the offset location of Operand 3 is the translated character. This char- 
acter replaces the original character in the target. 


The following example shows the step-by-step results of this translate operation. The translate table 
for this example has the following hex value: C3D406C5D504C1C2C4C5C6C7C8CIC1ICE 


Hex 05040ED2D2E1E10F03 - Initial target value 

Hex 04040ED2D2E1E10F03 - After the 1st character is translated 

Hex 04D50ED2D2E1E10F03 - After the 2nd character is translated 

Hex 04D50ED2D2E1E10F03 - SO character encountered, skip the DBCS portion 
Hex 04D50ED2D2E1E10F03 - Resume translating after SI control character 


Hex 04D50ED2D2E1E10FCS - Translate 9th character 
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es, 


Hex O04D50ED2D2E1E10FC5 - Final target value 


Translate with Table and DBCS Skip (XLATWTDS) 


The translate table, Operand 3, is assumed to be 256 bytes long. If the table is less than 256 charac- 
ters long, and a target character specifies an offset beyond the end of the table, the resultant charac- 
ters are obtained from byte locations in the space following translate table. If that portion of the space 
is not currently allocated, a space addressing (hex 0601) exception is signaled. 


This operation only translates the target string and does not validate the Double byte portions of the 
target. For example, if a DBCS portion of the target string is preceded by the Shift Out contro! char- 
acter, but missing the closing Shift In character, then an invalid extended character data (hex 0C12) 


exception wili NOT be signaled. However, the Copy Extended Characters Left-Adjusted With Pad 


(CPYECLAP) instruction can be used to validate extended character data, if necessary. 


Exceptions 


Exception 


06 


08 


1C 


20 


22 


24 


2E 


32 


36 


Addressing 

01 Spacing addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 


44 Partial system object damage 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 
02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 


03 Scalar value invalid 


Space management 


Operands 


1 2 3 Other 


X X X 
X X X 
X X X 
X X X 
X X X 


X 
X 
X 
X X X 
X X X 
X 
X X X 
x x Xx 
X 
X X X 
X 
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Translate with Table and DBCS Skip (XLATWTDS) 


| Operands 
| Exception 1 2 3 Other 
| 01 space extension/truncation 4 
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Trim Length (TRIML) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
10A7 Receiver length Source string Trim character 


Operand 1: Numeric variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character(1) scalar. 


Description: The operation determines the resultant length of operand 2 after the character specified 
by operand 3 has been trimmed from the end of operand 2. The resulting [length is stored in operand 
1. Operand 2 is trimmed from the end as follows: if the rightmost (last) character of operand 2 is 
equal to the character specified by operand 3, the length of the trimmed operand 2 string is reduced by 
1. This operation continues until the rightmost character is no longer equal to operand 3 or the 
trimmed length is zero. If operand 3 is longer than one character, only the first (leftmost) character is 
used as the trim character. 


Operands 2 and 3 are not changed by this instruction. 


Exceptions 


Exception 1 2 3 Other 
06 Addressing 
01 Space addressing violation 
02 Boundary alignment 
03 Range 


x KK KM 
x KK KM 
x KK KM 


06 Optimized addressability invalid 


08 Argument/Parameter 


01 Parameter reference violation Xx ».4 X 


0c Computation 
0A Size X 


10 Damage Encountered 


44 Partial system object damage X 


1C Machine-Dependent Exception 
03 Machine storage limit exceeded X 


20 Machine Support 
02 Machine check X 
03 Function check xX 


22 Object Access 
01 Object not found X X X 
02 Object destroyed 
03 Object suspended X X xX 


08 object compressed X 


*< 
x 
x< 
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Trim Length (TRIML) 


Operands 
Exception 1 2 3 Other 
24 Pointer Specification 
01 Pointer does not exist X X X >) 
02 Pointer type invalid X X X 
2E Resource Control Limit 
01 User Profile storage limit exceeded X 
32 Scalar Specification 
01 Scalar type invalid X X X 
36 Space Management 
01 Space Extension/Truncation X 
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Verify (VERIFY) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 
VERIFY Receiver Source Class 

10D7 

VERIFYB Branch options Receiver Source Class Branch targets 
1CD7 

VERIFY! Indicator Receiver Source Class Indicator targets 
18D7 options 


Operand ?: Binary variable scalar or binary array. 
Operand 2: Character scalar. 
Operand 3: Character scalar. 


Operand 4-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e indicator Form-Numeric variable scalar or character variable scalar. 


Description: Each character of the source operand character string value is checked to verify that it is 
among the valid characters indicated in the class operand. 


The operation begins at the left end of the source string and continues character by character, from left 
to right. Each character of the source vaiue is compared with the characters of the class operand. Ifa 
match for the source character exists in the class string, the next source character is verified. Ifa 
match for the source character does not exist in the class string, the binary value for the relative 
location of the character within the source string is placed in the receiver operand. 


If the receiver operand is a scalar, only the first occurrence of an invalid character is noted. Ifthe 
receiver operand is an array, aS many occurrences as there are elements in the array are noted. 


The operation continues until no more occurrences of invalid characters can be noted or until the end 
of the source string is encountered. When the second condition occurs, the current receiver value is 
set to 0. If the receiver operand is an array, all its remaining entries are set to 0’s. 


The source and class operands can be variable length substring compound operands. 


Substring operand references that allow for a null substring reference (a length value of zero) may be 
specified for operands 2 and 3. The effect of specifying a null substring reference for the class 
Operand when a nonnull string reference is specified for the source is that all of the characters of the 
source are considered invalid. In this case, the receiver is accordingly set with the offset(s) to the 
bytes of the source, and the instruction’s resultant condition is positive. The effect of specifying a null 
substring reference for the source operand (no characters to verify) is that the receiver is set to zero 
and the instruction’s resultant condition is zero regardless of what is specified for the class operand. 


Resultant Conditions: The numeric value(s) of the receiver is either 0 or positive. When the receiver 
operand is an array, the resultant condition is 0 if all elements are 0. 


Exceptions 
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Exception 


06 


08 


10 


1C 


20 


22 


24 


2C 


2E 


36 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 branch target invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Verify (VERIFY) 


1 2 3 Other 


x KK OK 
x KK OK 
x KK 


X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
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Date/Time/Timestamp Instructions 


Chapter 3. Date/Time/Timestamp Instructions 


This chapter describes all instructions used for date, time, and timestamp use. These instructions are 
in alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary” 


EXtehidl Data FOrMals:  4:4ci svi ot +e accu dente ee ba oS Se ek oe 3-3 
Date, Time, and Timestamp Concepts ..........0...0 000. ee eee ee ee ee 3-3 
Compute Date Duration: (CODD): «2244.24 24886568 8% doe oe be ee he Dee eh Owe Es 3-13 
Compute Time Duration (CTD) ........0.0.. 00.0.0. ee ee es 3-16 
Compute Timestamp Duration (CTSD) .......0.0.. 0.0... eee 3-19 
Conver Dalte(CVED): ao.n 6 ese ee dee eter ee oh Soe Mw eh Mi ed Ale aes GRE wd ee 3-22 
CONVErl TIME(CVT): Soe & & ee wat ei ee A eG De SE eh ee ee a a ee 3-25 
Convert Timestamp (CVTTS) .......0.0 2.0... 000. ce eee ee ee ee We we ele oe oo 3-28 
Decrement Date (DECD) «jackie SR oA WE FRA BSS DR EEE EES EERE EERE ST «ES 3-31 
Decrement Time (DECT). accuciatt yet ceo RA al eat ee ene he ee BS, ee eh, eh eee 3-35 
Decrement Timestamp (DECTS) .........0..0 0.0... 2.0.0 2. cee ee en 3-38 
INGFEMENT Date CINGD) iced a ded, aoe Ge dee we hh he ease We oh Ne a hee he eS: ee A 3-42 
Increment: TiMmetINGW): . 422% 2 4 Be eee ws de ew eee eee eae a eS ee ee 3-46 
Increment Timestamp (INCTS) .. 0... 2.20.00. 00 eee ee ee 3-49 
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Date/Time/Timestamp Instructions 


External Data Formats 


For support of date, time, and timestamp, the external data format that is used is a character string. 
Associated with this character string will be a data definitional attribute list (DDAT) that describes all 
the attributes of the string. 
The attributes that are associated with the character string are as follows: 

e Calendar table. 

¢ Era table. 

e Format code. 

e Date separator type. 

e Time separator type. 

¢ Time zone. 

¢ Month definition. 

¢ Year definition. 


* Century. 


Date, Time, and Timestamp Concepts 


Data Definitions 


DATE. Date data type. The internal format is a 4 byte binary value. The DDAT number must reference 
a DDAT with an internal DATE format code or be set to zero which implies internal format. The 
internal format is fixed length, trailing blanks are NOT allowed. 


TIME. Time data type. The internal format is six numbers packed into a three byte value. There is no 
sign nibble. The DDAT number must reference a DDAT with an internal TIME format code or be set to 
zero which implies internal format. The internal format is fixed length, trailing blanks are NOT allowed. 


TIMESTAMP. Timestamp data type. The internal format of a Timestamp is a ten byte composite value. 
The composite is two numbers one for date and time respectfully. The date and time numbers have the 
same encoding as the date and time data types, with an exception to the time number. The time 
number has an additional 3 bytes for a six packed digit microsecond value. The DDAT number must 
reference a DDAT with an internal Timestamp format code or be set to zero which implies internal 
format. The internal format is fixed length, trailing blanks are NOT allowed. 


PseudoDATE. Character data type with a DDAT referenced. The DDAT number must reference a DDAT 
with a valid date format code. The character string format must match one of the supported formats, 
trailing blanks are allowed. The length is the number of bytes of the character string which can 
include trailing blanks. " 


PseudoTIME. Character data type with a DDAT referenced. The DDAT number must reference a DDAT 
with a valid time format code. The character string format must match one of the supported formats, 
trailing blanks are allowed. The length is the number of bytes of the character string which can 
include trailing blanks. 


PseudoTIMESTAMP. Character data type with a DDAT referenced. The DDAT number must reference 
a DDAT with a valid timestamp format code. The character string format must match one of the sup- 
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ported formats, trailing blanks are allowed. The length is the number of bytes of the character string 
which can include trailing blanks. 


DATE DURATION. Packed decimal data type with a DDAT referenced. The length must be 8,0. The J 
DDAT number is set to reference a DDAT with a valid date duration format code. 


TIME DURATION. Packed decimal data type with a DDAT referenced. The length must be 6,0. The 
DDAT number must reference a DDAT with a valid time duration format code. 


TIMESTAMP DURATION. Packed decimal data type with a DDAT referenced. The length must be 20,6. 
The DDAT number must reference a DDAT with a valid timestamp duration format code. 


DATE LABEL DURATIONS. Packed decimal data type with a DDAT referenced. The length must be 
15,0. The DDAT number must reference a DDAT with a valid date label duration format code. 


TIME LABEL DURATIONS. Packed decimal data type with a DDAT referenced. The length must be 
15,0. The DDAT number must reference a DDAT with a valid time label duration format code. 


TIMESTAMP LABEL DURATIONS. Packed decimal data type with a DDAT referenced. The length must 
be 15,0. The DDAT number must reference a DDAT with a valid timestamp label duration format code. 


Data Conversion 


The following table describes the possible conversions for date/time data. 


Source Operand Result Operand : 
DATE DATE or PseudoDATE ‘ 
TIME TIME or PseudoTIME J 
TIMESTAMP TIMESTAMP or PseudoTIMESTAMP 

PseudoDATE DATE or PseudoDATE 

PseudoTIME TIME or PseudoTIME 

PseudoTIMESTAMP TIMESTAMP or PseudoTIMESTAMP 

Arithmetic 


For all Date/Time arithmetic, Increment, Decrement, and Compute, there must be at least one non-zero 
DDAT number specified between operand 1, operand 2, and the result. 


DDATs are equivalent when both DDAT numbers are 0 or both DDAT numbers are non-zero and the 
DDATs they reference are byte for byte identical. 


End of month adjustment can only be specified in conjunction with Date and Timestamp arithmetic that 
involves the incrementing and decrementing of Dates or Timestamps. 


When end of month adjustment is specified, there must be at least one non-internal format specified for 
operand 1, operand 2, or the result. When end of month adjustment is not specified all durations must 
reference a DDAT that specifies a year and month definition other than zero. 
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Data Definitional Attribute Template 


The following describes the Data Definitional Attribute Template (DDAT). 


e Data definitional attribute template (optional) Char(112-n) 
(repeated for each operand/field that requires a template, one template can be used by multiple 
Operands/fields that have the same attributes) 


— DDAT length (ignored) UBin(2) 
— Format code UBin(2) 
— Separator definition Char(2) 
- Date separator type Char(1) 
- Time separator type Char(1) 
— Time zone definition Char(4) 
- Hour zone UBin(2) 
- Minute zone UBin(2) 
— Duration definitions Char(4) 
- Month definition UBin(2) 
- Year definition UBin(2) 
— Century definition _Char(8) 
- Current century . UBin(4) 
- Century division UBin(4) 
— Calendar table offset UBin(4) 
— Reserved (binary 0) Char(6) 
— Era table template Char(50-n) 
— Calendar table template Char(18-n) 


The following table describes the operand type and DDAT field associations. 
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Operand Format. Date Time Time Month Year Century Era Calendar 
Type Code Sepa- Sepa- zone Defi- Defi- Table Table 

" rator rator nition nition J 
Date REQ REQ INV INV INV INV REQ REQ REQ 
Time REQ INV REQ REQ INV INV INV INV INV 
Timestamp REQ REQ REQ REQ INV INV REQ REQ REQ 
Pseudo REQ REQ INV INV INV INV REQ REQ REQ 
Date 
Pseudo REQ INV REQ REQ INV INV INV INV INV 
Time 
Pseudo REQ REQ REQ REQ INV INV REQ REQ REQ 
Timestamp 
Date Dura- REQ INV INV INV EMA EMA INV INV INV 
tion 
Time Dura- REQ INV INV INV INV INV INV INV INV 
tion 
Timestamp REQ INV INV INV EMA EMA INV INV INV 
Duration 
Year Label REQ INV INV INV EMA EMA INV INV INV 
Duration 
Month REQ INV INV INV EMA EMA INV INV INV 
Label Dura- : 
tion 
Day Label REQ INV INV INV EMA EMA INV INV INV i 
Duration J 
Hour Label REQ INV INV INV INV INV INV INV INV 
Duration 
Minute REQ INV INV INV INV INV INV INV INV 
Label Dura- 
tion 
Second REQ INV INV INV INV INV INV INV INV 
Label Dura- 
tion 
Micro- REQ INV INV INV INV INV INV INV INV 
second 
Label Dura- 
tion 
Notes: 


REQ The DDAT field is required and the value must be non-zero. 
INV The DDAT field is invalid and the value must be Zero. 


EMA The DDAT field is required to have a zero value for end of month adjustment arithmetic. Other- 
wise the field value is required to be non-zero. 


The DDAT length the length of the DDAT in bytes. This field is ignored by the instruction. 


The following describes the format code The formats are use to define the representation or interpreta- 
tion of data across the MI. They also imply the length of the data. } 
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USA date 

USA time 

ISO date 

ISO time 

EUR date 

EUR time 

JIS date 

JIS time 

SAA timestamp 

System internal date 
System internal time 
System internal timestamp 
Labeled duration YEAR 
Labeled duration MONTH 
Labeled duration DAY 
Labeled duration HOUR 
Labeled duration MINUTE 
Labeled duration SECOND 
Labeled duration MICROSECOND 
Date duration 

Time duration 

Timestamp duration 
*MMDDYY 

*DDMMYY 

*YYMMDD 

*YYDDD 

*HHMMSS 

IMPI clock 

*YYYYDDD 
*YYYYMMDDhhmmss 
*Unknown date 
*Unknown time 


*Unknown timestamp 


Format 
Code 


Hex 0001 
Hex 0002 
Hex 0003 
Hex 0004 
Hex 0005 
Hex 0006 
Hex 0007 
Hex 0008 
Hex 0009 
Hex 000A 
Hex 000B 
Hex 000C 
Hex 000D 
Hex OO0E 
Hex OOOF 
Hex 0010 
Hex 0011 
Hex 0012 
Hex 0013 
Hex 0014 
Hex 0015 
Hex 0016 
Hex 0017 
Hex 0018 
Hex 0019 
Hex 001A 
Hex 001B 
Hex 001C 
Hex 001D 
Hex 001E 
Hex 001F 
Hex 0020 
Hex 0021 


Minimum 
Input 
Length 


bh © AR @O N 


bh =—- R & 
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Maximum 
Input 
Length 


n 
n 
n 
n 
n 


n 


& 
oO 


nN 
S 
yo) 


ee > > a °- > > Se ae | 3 


a | 


Minimum 
Output 
Length 


10 
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Maximum 
Output 
Length 


n 
n 
n 
n 


n 
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Format Type 


USA date 

USA time 

ISO date 

ISO time 

EUR date 

EUR time 

JIS date 

JIS time 

SAA timestamp 

System internal date 
System internal time 
System internal timestamp 
Labeled duration YEAR 
Labeled duration MONTH 
Labeled duration DAY 
Labeled duration HOUR 
Labeled duration MINUTE 
Labeled duration SECOND 
Labeled duration MICROSECOND 
Date duration 

Time duration 

Timestamp duration 
*MMDDYY 

*DDMMYY 

*YYMMDD 

*YYDDD 

*HHMMSS 

IMPI clock 

*YYYYDDD 
*YYYYMMDDhhmmss 
*Unknown date 
*Unknown time 


*Unknown timestamp 


Notes: 


Format 
Code 


Hex 0001 
Hex 0002 
Hex 0003 
Hex 0004 
Hex 0005 
Hex 0006 
Hex 0007 
Hex 0008 
Hex 0009 
Hex 000A 
Hex 000B 
Hex 000C 
Hex 000D 
Hex 000E 
Hex O00OF 
Hex 0010 
Hex 0011 
Hex 0012 
Hex 0013 
Hex 0014 
Hex 0015 
Hex 0016 
Hex 0017 
Hex 0018 
Hex 0019 
Hex 001A 
Hex 001B 
Hex 001C 
Hex 001D 
Hex 001E 
Hex 001F 
Hex 0020 
Hex 0021 


Preferred 
Format 


~“<~<<<<<< <<< <« < 


~<<<<<< << 


‘n’ - Any number which is greater than minimum length. 


‘Y’ - Allowed. 
’N’ - Not allowed. 


’* ~ Not applicable. 
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Search 
List 


zz2<<< << << < <x 


<~<2222z222z2 


Character 
data type 


<< << <~< << << ~~ < 2222222222<“4<“4<4~<%<+< <~« ~« ~« <~« <« < 


Packed 
decimal 


data type 


N 


Zz_a2z222 2 2 2 222 244% €& €& ~*~ K€ € KK KA AzZAA Bz AAA A A AZZ 
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J 


Date/Time/Timestamp Instructions 


‘F’ - Reference the formats for this value. 


ay 


- Date, time, and timestamp data types the length is fixed 4, 3, and 10 respectfully. For the character 


data type the length Is variable. 


For further information on the SAA formats reference the SAA CPI Database Reference. The following 
are the descriptions of the formats, D represents days, M represents months, Y represents years, h 
represents hours, m represents minutes, s represents seconds and u represents microseconds. 


USA 
— Date - MM/DD/YYYY, character string. 


— Time - hh:mm AM or PM, character string. 00:00 AM or 12:00 AM is midnight. 12:00 PM is noon. 
Between ‘hh:mm/’ and ‘AM’ or ’PM’ only one one blank is allowed. 


ISO 

— Date - YYYY-MM-DD, character string. 
— Time - hh.mm.ss, character string. 
EUR 

— Date -DD.MM.YYYY, character string. 
— Time - hh.mm.ss, character string. 
JIS 

— Date - YYYY-MM-DD, character string. 
— Time - hh:mm:ss, charracter string. 
SAA timestamp 


— Timestamp - YYYY-MM-DD-hh.mm.ss.uuuuuu, character string. Leading zeros maybe omitted 
from the month, day, and hour part of the timestamp, and microseconds may be truncated or 
entirely omitted, (.10 = .100000). 


System internal format 
— Date - 4 byte binary Scaliger number 


— Time - 3 byte value with each byte containing two packed decimal digits having the encoding of 
hhmmss. 


— Timestamp - 10 byte composite number, the first part being a 4 byte internal date and the 
second part being a 3 byte internal time, plus microseconds, a 3 byte value with each byte 
containing two packed decimal digits having the encoding of uuUuUUU. 


Labeled durations 


— They are a 15,0 packed decimal data value. The keywords; YEARS, MONTHS, DAYS, HOURS, 
MINUTES, SECONDS, and MICROSECONDS, or the singular form of the keywords; YEAR, 
MONTH, DAY, HOUR, MINUTE, SECOND, and MICROSECOND, are not part of the data. 


Date duration 


— Packed decimal (8,0) number having the encoding of YYYYMMDD, where YYYY has the range 0 
- 9999, MM has the range 0 - 99, and DD has the range 0 - 99. 


Time duration 


— Packed decimal (6,0) number having the encoding of hhmmss, where hh has the range 0 - 99, 
mm has the range 0 - 99, and ss has the range O - 99. 


Timestamp duration 
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Date/Time/Timestamp Instructions 


— Packed decimal (20,6) number having the encoding of YYYYMMDDhhmmssuuuuuu, where in 
addition to date and time, uuuuuu has the range 0 - 999999. 


¢ *MMDDYY J 


— Date - MMDDYY, character string 
« *DODMMYY 
— Date - DDMMYY, character string 
© *YYMMDD 
— Date - YYMMDD, character string 
e *YYDDD 
— Date - YYDDD, character string 
¢ *HHMMSS 
— Time -hhmmss, character string 
e |IMPI clock 
— It is an 8 byte bit clock, which is used as a timestamp. 
e *YYYYDDD 
— Date - YYYYDDD, seven character string. Used on the DATE scalar function. 
e *YYYYMMDDhhmmss 
— Timestamp - YYYYMMDDhhmmss fourteen character string. 
« *Unknown f 


— Used to reference unique SAA formats. This format is used only when the format is NOT a 
known. This format tries to find a matching format. The formats that will be scanned for are; 
USA, ISO, EUR, JIS, dates and times, *YYYYDDD (date), SAA timestamp, and 
*YYYYMMDDhhmmss timestamp. When a valid match is not found either a data, format or 
value, exception will be signalled. 


The following describes the separator definitions for date and time. The separator type is a one char- 
acter field that contains the separator value, for example, :, ., /, or -. When the format has an implied 
separator, the implied separator is used. For example, an ISO date, the implied separator is ’-’. When 
the format does not have an implied separator, the implied separator is null. For example, the format 
“YYMMDD has an implied separator of null. A null separator means the units of time, year, month, day, 
etc..., are concatenated together. A implied separator is specified by using the value of hex ‘00’. A 
null separator is specified by using the value of hex ’FF’. A null separator is invalid for the SAA 
formats, USA, ISO, etc... Any other separator value overrides the implied value for the format code. 


The following describes the time zone definition. The hour zone value is 0 to 24. GMT zone is 0. The 
zone to the east of zone 0 is zone 1. The zone to the east of zone 1 is zone 2, and so on. The value 24 
specifies that the time is to be stored as local time and that the concept of time zones should be 
ignored. The value of 24 is required for storage purposes. For example, when inserting a time field 
into a database data space the hour Zone value must be 24. A value other than 24 can be used for 
retrieval purposes. 


The minute Zone value is 0 to 60. GMT zone is 0. The zone to the west of zone 0 is zone 1. The zone to 
the west of zone 1 is zone 2, and so on. The value 60 specifies that the time is to be stored as local 
time and that the concept of time zones should be ignored. The value of 60 is required for storage 
purposes. For example, when inserting a time field into a database data space the minute zone value 
must be 60. A value other than 60 can be used for retrieval purposes. 
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The month definition is an integer number of days. For example 30, would specify that each month use 
in a duration would have a constant value of 30 days. The a value of zero specifies that the calendar 
definition of the month should be used. 


The year definition is an integer number of days. For example 365, would specify that each year use in 
a duration would have a constant value of 365 days. The a value of zero specifies that the calendar 
definition of the year should be used. 


When end of month adjustment arithmetic is being performed, the month definition and year definition 
must have zero values. When no end of month adjustment arithmetic is being performed, the month 
definition and year definition must have non-zero values. Otherwise a template value invalid (hex 3801) 
exception will be signaled. 


The century fleld is used to define the century when a two digit year is specified for a date. The defi- 
nition is two numbers, one for current century and the other is for the century division year. The 
current century is a century number. The century division is a year number. The valid values for the 
current century are 0-99. The valid values for the century division are 0 - 99. The century division is 
included in the current century. For example, a current century of 19 and a century division of 50 
would result in two digit years 00 - 49, having the values 2000 - 2049 and 50 - 99 having values 1950 - 
1999. 


The calendar table offset is the number of bytes from the start of the DDAT to the start of the calendar 
table (described below). 


Era Table 
The era table immediately follows the fixed portion of the DDAT. 


The following describes the era tabie data. 


e Number of table elements UBin(2) 

e Era element (repeatable) Char(48) 
— Origin date UBin(4) 
— Era name Char(32) 
— Reserved (binary 0) Char(12) 


The era table is a list of elements that state what era should be used across the time line. The start of 
usage of a particular era is specified by the origin date. The end of usage of a particular era is termi- 
nated by the next table element. The last table element era is used until the end of the time line. The 
origin date is specified in the internal format. The era name is a character field. The maximum 
number of table entries allowed is 256. 


The SAA era table has one entry. The SAA origin date is January 1, 0001, Gregorian for the start of the 
time line. The internal format would be 1721424. The SAA name is AD, anno Domini. 


The SAA era table can have only one element and that element must have an effective date that falls 
in the time line specified in the SAA calendar table. 
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Calendar Table 


The following describes the calendar table data. 


¢ Number of table elements 

e Calendar change element (repeatable) 
— Effective date 
— Calendar type 
— Reserved (binary 0) 


Date/Time/Timestamp Instructions 


UBin(2) 
Char(16) 
UBin(4) 
UBin(2) 
Char(10) 


The calendar table is a list of elements that state what calendar type/algorithm should be used across 
the time line. The start of usage of a particular calendar is specified by the effective date. The effective 
date is specified using the internal format. This first table element represent the beginning of the time 
line. The end of usage of a particular calendar is terminated by the next table element. The last table 
element calendar must be null this indicates the end of the time line. The maximum number of table 


entries allowed is 256. 


The SAA calendar table has 2 entries. The first entry has a calendar type of Gregorian. The effective 
date is January 1, 0001, Gregorian for the start of the time line. The internal format would be 1721424. 
The second entry has a calendar type of null. The effective date is January 1, 10000, Gregorian for the 
end of the time line. The internal format would be 5373485. 


Multiple calendar table entries are only valid with DDATs specifying the internal date format code. The 
rest of format codes can only have two entries in the calendar table. The second entry must have a 


NULL calendar type. 


The following describes the encoding of the calendar types. J 
Calendar type Calendar type value 

Null Hex 0000 

Gregorian Hex 0001 

Julian Hex 0002 

Muslim Hex 0003 

Hebrew Hex 0004 
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Compute Date Duration (CDD) 


Op Code (Hex) Operand 1 Operand 2 
0424 Date duration Date 1 
Operand 1: Packed decimal variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character scalar. 
Operand 4: Space pointer. 
ILE access 

CDD ( 

var date duration : packed decimal; 

var datel : aggregate; 

var date2 : aggregate; 


instruction template : space pointer 


Compute Date Duration (CDD) 


Operand 3 Operand 4 
Date 2 Instruction template 


Description: The date specified by operand 3 is subtracted from the date specified by operand 2 and 
the value of the results a duration is place in operand 1. Operand 4 defines the data definitional attri- 
butes for operands 1 through 3. 


A negative value will be returned when the first operand is less than the second operand. 


The following describes the instruction template. 


e Instruction template 


— Instruction template size 


— Operand 1 data definitional attribute template number 


— Operand 2 data definitional attribute template number 


— OQOperand 3 data definitional attribute template number 


— Reserved (binary 0) 


— QOperand 2 length 


— Operand 3 length 


— Reserved (binary 0) 


— Data definitional attribute template list 


Size of the DDAT list 
Number of DDATs 
Reserved (binary 0) 
DDAT offset (repeated) 


Data definitional attribute template (repeated) 


Char(*) 
UBin(4) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
UBin(2) 
Char(26) 
Char(*) 
UBin(4) 
UBin(2) 
Char(10) 
UBin(4) 
Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute template list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


Chapter 3. Date/Time/Timestamp Instructions 3-13 


Compute Date Duration (CDD) 


The DDAT for operand 1 must be valid for a date duration. The DDATs for operands 2 and 3 must be 
valid for a date and identical. Otherwise, a template value invalid (hex 3801) exception will be sig- 


naled. J 


Operand 2 length and operand 3 length are specified in number of bytes. 
The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 3. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the character operands will be defined by the tem- 
plate. For a further description of the data definitional attribute template, see “Data Definitional Attri- 
bute Template” on page 3-5 


Authorization Required 


e None. 


Lock Enforcement 


e¢ None. 


Exceptions J 


Operands 
Exception 1 2 3 4 Other 


06 Addressing 
01 Space addressing violation 
02 Boundary alignment 
03 Range 
06 Optimized addressability invalid 


x KK RK 
x KK OK 
<x KK RK 
x KX K RK 


08 Argument/Parameter 


~x< 
x< 
~*~ 


01 Parameter reference violation X 


oc Computation 
15 Data boundary overflow 
16 Data format 


17 Data value 


x «KK 
x Km KK 


18 Date boundary underflow 


10 Damage Encountered 


04 System object damage state X X X X X 


~< 
x< 
x< 
x< 


44 Partial system object damage X 


20 Machine Support 
02 Machine check X 2 
03 Function check Xx 
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Exception 


22 


24 


Ze 


32 


36 


38 


Object Access . 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 


01 Template value invalid 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 
X 
X 


Compute Date Duration (CDD) 


Other 
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Compute Time Duration (CTD) 


Operand 2 
Time 1 


Op Code (Hex) Operand 1 
0454 Time duration 


Operand 1: Packed decimal variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character scalar. 


Operand 4: Space pointer. 


ILE access 
CTD ( 
var time_duration : packed decimal; 
var timel : aggregate; 
var time2 : aggregate; 


instruction template : space pointer 


Compute Time Duration (CTD) 


Operand 4 2 


Instruction template 


Operand 3 
Time 2 


Description: The time specified by operand 3 is subtracted from the time specified by operand 2 and 
the value of the results a duration is place in operand 1. Operand 4 defines the data definitional attri- 


butes for operands 1 through 3. 


t 
A negative value will be returned when the first operand is less than the second operand. J 


The following describes the instruction template. 
e Instruction template 


— Instruction template size 


— Operand 1 data definitional attribute template number 
— Operand 2 data definitional attribute template number 


— QOperand 3 data definitional attribute template number 


— Reserved (binary 0) 
— Operand 2 length 
— Operand 3 length 
— Reserved (binary 0) 
— Data definitional attribute template list 
- Size of the DDAT list 
- Number of DDATs 
- Reserved (binary 0) 
- DDAT offset (repeated) 


- Data definitional attribute template (repeated) 


Char(*) 
UBin(4) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
UBin(2) 
Char(26) 
Char(*) 
UBin(4) 
UBin(2) 
Char(10) 
UBin(4) 
Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 2 
tion of a template in the data definitional attribute template list. For example the number 1 references 
the first template. The valid values for this field are 1, 2, and 3. 
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Compute Time Duration (CTD) 


The DDAT for operand 1 must be valid for a time duration. The DDATs for operands 2 and 3 must be 
valid for a time and identical. Otherwise, a template value invalid (hex 3801) exception will be sig- 
naled. 


Operand 2 length and operand 3 length are specified in number of bytes. 
The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 3. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the character operands will be defined by the tem- 
plate. For a further description of the data definitional attribute template, see “Data Definitional Attri- 
bute Template” on page 3-5 


Authorization Required 


e None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range X X X X 
06 Optimized addressability invalid X X X X 
08 Argument/Parameter 
01 Parameter reference violatian X X X X 
0c Computation 
16 Data format X X 
17 Data value X X 
10 Damage Encountered 
04 System object damage state X X X X X 
44 Partial system object damage X X X X X 
20 Machine Support 
02 Machine check X 
03 Function check X 
22 Object Access 
01 Object not found X X X X 
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Compute Time Duration (CTD) 


Operands 
Exception 1 2 3 4 Other | 
02 Object destroyed X X X X ; 
03 Object suspended X X X X 
24 Pointer Specification 
01 Pointer does not exist X X X X 
02 Pointer type invalid X X X X 
2E Resource Control Limit 
01 User Profile storage limit exceeded X 
32 Scalar Specification 
02 Scalar attributes invalid X X 
03 Scalar value invalid X X 
36 Space Management 
01 Space Extension/Truncation Xx 
38 Template Specification 
01 Template value invalid X 


C 
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Compute Timestamp Duration (CTSD) 


Op Code (Hex) Operand 1 Operand 2 
043C Timestamp dura- Timestamp 1 
tion 


Operand 1: Packed decimal variable scalar. 
Operand 2: Character scalar. 
Operand 3: Character scalar. 


Operand 4: Space pointer. 


ILE access 
CTSD ( 
var timestamp duration : packed decimal; 
var timestampl : aggregate; 
var timestamp2 : aggregate; 


instruction template : space pointer 


Description: The timestamp specified by operand 3 is subtracted from the timestamp specified by 


Compute Timestamp Duration (CTSD) 


Operand 3 
Timestamp 2 


Operand 4 


Instruction template 


operand 2 and the value of the results a duration is place in operand 1. Operand 4 defines the data 


definitional attributes for operands 1 through 3. 


A negative value will be returned when the first operand is less than the second operand. 


The following describes the instruction template. 
e Instruction template 
— Instruction template size 
— Operand 1 data definitional attribute template number 
— Operand 2 data definitional attribute template number 
— Operand 3 data definitional attribute template number 
— Reserved (binary 0) 
— Operand 2 length 
— Operand 3 length 
— Reserved (binary 0) 
— Data definitional attribute template list 
- Size of the DDAT list 
- Number of DDATs 
- Reserved (binary 0) 
- DDAT offset (repeated) 


- Data definitional attribute template (repeated) 
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Char(*) 
Bin(4) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
UBin(2) 
Char(26) 
Char(*) 
UBin(4) 
UBin(2) 
Char(10) 
UBin(4) 
Char(*) 
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Compute Timestamp Duration (CTSD) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 


tion of a template in the data definitional attribute template list. For example the number 1 references 
the first template. The valid values for this field are 1, 2, and 3. 


The DDAT for operand 1 must be valid for a timestamp duration. The DDATs for operands 2 and 3 
must be valid for a timestamp and identical. Otherwise, a emplate value invalid (hex 3801) exception 
will be signaled. 


Operand 2 length and operand 3 length are specified in number of bytes. 
The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 3. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the character operands will be defined by the tem- 
plate. For a further description of the data definitional attribute template, see :hdref=DDAT. 


Authorization Required 


e None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range X X X X 
06 Optimized addressability invalid X X xX X 
08 Argument/Parameter 
01 Parameter reference violation X X X X 
le Computation 
15 Data boundary overflow X X 
16 Data format X X 
17 Data value X X 
18 Date boundary underflow X X 
10 Damage Encountered 
04 System object damage state X X X X X 
44 Partial system object damage X X xX xX X 
20 Machine Support 
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Exception 


22 


24 


2E 


32 


36 


38 


02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 


01 Template value invalid 


Compute Timestamp Duration (CTSD) 


Operands 
1 2 3 4 Other 
X 
X 
X X X X 
X X X X 
X X X X 
X X X X 
X X X X 
X 
X X 
X X 
X 
X 
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Convert Date (CVTD) 


Op Code (Hex) Operand 1 Operand 2 


040F 


Result date Source date 


Operand ?: Character variable scalar. 


Operand 2: Character scalar. 


Operand 3: Space pointer. 


ILE access 
CVTD ( 
var result_date : aggregate; 
var source date : aggregate; 


instruction template : space pointer 


) 


Convert Date (CVTD) 


Operand 3 J 


Instruction tem- 
plate 


Description: The date specified in operand 2 is converted to another calendar external or internal 
presentation and placed in operand 1. Operand 3 defines the data definitional attributes for operands 1 


and 2. 


The following describes the instruction template. 


¢ Instruction template 


— Instruction template size 


— Operand 1 data definitional attribute template number 


— Operand 2 data definitional attribute template number 


— Reserved (binary 0) 


— OQOperand 1 length 


— QOperand 2 length 


— Reserved (binary 0) 


— Preferred/Found date format 


— Preferred/Found date separator 


— Reserved (binary 0) 


— Data definitional attribute template list 


Size of the DDAT list 
Number of DDATs 
Reserved (binary 0) 
DDAT offset (repeated) 


Data definitional attribute template (repeated) 


Char(*) J 


Bin(4) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
Char(1) 
Char(23) 
Char(*) 
UBin(4) 
UBin(2) 
Char(10) 
UBin(4) 
Char(*) 


A data definitional attribute template number is a number that corresponds to the relative position of a 4 
template in the data definitional attribute template list. For example the number 1 references the first 


template. The valid values for this field are 1 and 2. 
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Convert Date (CVTD) 


The DDATs for operands 1 and 2 must be valid for a date. Otherwise, a template value invalid (hex 
3801) exception will be signaled. 


Operand 1 length and operand 2 length are specified in number of bytes. 


lf the data definitional attribute template numbers for operands 1 and 2 are the same, only data vali- 
dation is performed. The validation will check for format and data value correctness. 


A format of unknown date, time, or timestamp will indicate that operand 2 will be scanned for a valid 
format. For a list of formats that can be scanned, see “Data Definitional Attribute Template” on 

page 3-5. With an unknown format, the preferred/found format and preferred/found separator can be 
specified to select an additional non-scannable format. This preferred format and preferred separator 
will be used first to find a matching format before scanning operand 2. When the preferred format and 
preferred separator have a hex value of zero, only the scan occurs. 


When a format of unknown date, time, or timestamp is specified, the preferred/found format and 
preferred/found separator fields will be set to the format and separator found. 


The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 2. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the character operands will be defined by the tem- 
plates. For a further description of the data definitional attribute template, see “Data Definitional Attri- 
bute Template” on page 3-5. 


Authorization Required 


e None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 Space addressing violation X X X 
02 Boundary alignment X X X 
03 Range Xx xX X 
06 Optimized addressability invalid X Xx xX 
08 Argument/Parameter 
01 Parameter reference violation X X X 
0c Computation 
15 Data boundary overflow X Xx 
16 Data format X 


Chapter 3. Date/Time/Timestamp Instructions 3-23 


Exception 


10 


20 


22 


24 


2E 


32 


36 


38 


17 Data value 


18 Date boundary underflow 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 
Resource Control Limit 
01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 
Template Specification 


01 Template value invalid 


Convert Date (CVTD) 


Operands 

1 2 3 Other 
X 
X X 


X 
X 
X X X 
X X X 
X X X 
X X X 
X X X 
X 
X X 
X X 
X 
X 
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Convert Time (CVTT) 


Convert Time (CVTT) 


c Op Code (Hex) Operand 1 Operand 2 Operand 3 
041F Result time Source time Instruction tem- 
plate 


Operand f: Character variable scalar. 
Operand 2: Character scalar. 


Operand 3: Space pointer. 


| ILE access 
CVIT ( 
var result_time : aggregate 
var source time : aggregate 


| 
| 
| 
| instruction template : space pointer 
| 


Description: The time specified in operand 2 is converted to another external or internal presentation 
and placed in operand 1. Operand 3 defines the data definitional attributes for operands 1 and 2. 


The following describes the instruction template. 


e Instruction template Char(*) 
Ss — Instruction template size Bin(4) 
— QOperand 1 data definitional attribute template number UBin(2) 
— QOperand 2 data definitional attribute template number UBin(2) 
— Reserved (binary 0) Char(2) 
— Operand 1 length UBin(2) 
— Operand 2 length UBin(2) 
— Reserved (binary 0) Char(2) 
— Preferred/Found time format UBin(2) 
— Reserved (binary 0) Char(1) 
— Preferred/Found time separator — Char(1) 
— Reserved (binary 0) Char(22) 
— Data definitional attribute template list Char(*) 
- Size of the DDAT list UBin(4) 
- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 
Se A data definitional attribute template number is a number that corresponds to the relative position of a 


template in the data definitional attribute template list. For example the number 1 references the first 
template. The valid values for this field are 1 and 2. 


Chapter 3. Date/Time/Timestamp Instructions 3-25 


Convert Time (CVTT) 


The DDATs for operands 1 and 2 must be valid for a time. Otherwise, a template value invalid (hex 
3801) exception will be signaled. 


Operand 1 length and operand 2 length are specified in number of bytes. 


If the data definitional attribute template numbers for operands 1 and 2 are the same, only data vali- 
dation is performed. The validation will check for format and data value correctness. 


A format of unknown date, time, or timestamp will indicate that operand 2 will be scanned for a valid 
format. For a list of formats that can be scanned, see “Data Definitional Attribute Template” on 

page 3-5. With an unknown format, the preferred/found format and preferred/found separator can be 
specified to select an additional non-scannable format. This preferred format and preferred separator 
will be used first to find a matching format before scanning operand 2. When the preferred format and 
preferred separator have a hex value of zero, only the scan occurs. 


When a format of unknown date, time, or timestamp is specified, the preferred/found format and 
preferred/found separator fields will be set to the format and separator found. 


The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 2. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the character operands will be defined by the tem- t 
plates. For a further description of the data definitional attribute template, see “Data Definitional Attri- ie 
bute Template” on page 3-5. 


Authorization Required 


e None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x KX K RK 
x KX K XK 
x KX K OK 


08 Argument/Parameter 
01 Parameter reference violation D4 Xx X 

oc Computation | ) 
16 Data format xX 
17 Data value X 
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Exception 


10 


20 


22 


24 


2E 


32 


36 


38 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 
01 Space Extension/Truncation 
Template Specification 


01 Template value invalid 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X 
X 


Convert Time (CVTT) 


x 


Other 
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Convert Timestamp (CVTTS) 


Op Code (Hex) Operand 1 Operand 2 
043F Converted Input timestamp 
timestamp 


Operand 7: Character variable scalar. 


Operand 2: Character scalar. 


Operand 3: Space pointer. 


ILE access 
CVTTS ( 
var result_timestamp : aggregate 
var source timestamp : aggregate 


) 


instruction template : space pointer 


Convert Timestamp (CVTTS) 


Operand 3 
Instruction tem- 
plate 


Description: The timestamp specified in operand 2 is converted to another external or internal presen- 
tation and placed in operand 1. Operand 3 defines the data definitional attributes for operands 1 and 2. 


The following describes the instruction template. 


e Instruction template 


Instruction template size 
Operand 1 data definitional attribute template number 
Operand 2 data definitional attribute template number 
Reserved (binary 0) 
Operand 1 length 
Operand 2 length 
Reserved (binary 0) 
Preferred/Found timestamp format 
Preferred/Found date separator 
Preferred/Found time separator . 
Reserved (binary 0) 
Data definitional attribute template list 
- Size of the DDAT list 
- Number of DDATs 
- Reserved (binary 0) 
- DDAT offset (repeated) 


- Data definitional attribute template (repeated) 


Char(*) 
Bin(4) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
UBin(2) 
Char(2) 
UBin(2) 
Char(1) 
Char(1) 
Char(22) 
Char(*) 
UBin(4) 
UBin(2) 
Char(10) 
UBin(4) 
Char(*) 


A data definitional attribute template number is a number that corresponds to the relative position of a 
template in the data definitional attribute template list. For example the number 1 references the first 
template. The valid values for this field are 1 and 2. 
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Convert Timestamp (CVTTS) 


The DDATs for operands 1 and 2 must be valid for a timestamp. Otherwise, a template value invalid 
(hex 3801) exception will be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


lf the data definitional attribute template numbers for operands 1 and 2 are the same, only data vali- 
dation is performed. The validation will check for format and data value correctness. 


A format of unknown date, time, or timestamp will indicate that 


A format of unknown date, time, or timestamp will indicate that operand 2 will be scanned for a valid 
format. For a list of formats that can be scanned, see “Data Definitional Attribute Template” on 

page 3-5. With an unknown format, the preferred/found format and preferred/found separator can be 
specified to select an additional non-scannable format. This preferred format and preferred separator 
will be used first to find a matching format before scanning operand 2. When the preferred format and 
preferred separator have a hex value of zero, only the scan occurs. 


When a format of unknown date, time, or timestamp is specified, the preferred/found format and 
preferred/found separator fields will be set to the format and separator found. 


The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 2. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the character operands will be defined by the tem- 
plates. For a further description of the data definitional attribute template, see “Data Definitional Attri- 
bute Template” on page 3-5. 


Authorization Required 


e None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 


01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x KK K 
x KK KR 
x KK K 


08 Argument/Parameter 
01 Parameter reference violation 4 X Xx 
oc Computation 
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Exception 


10 


20 


22 


24 


2E 


32 


36 


38 


15 Data boundary overflow 
16 Data format 
17 Data value 


18 Date boundary underflow 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 
02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Contro! Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 


01 Template value invalid 


Convert Timestamp (CVTTS) 


Operands 
1 2 3 Other 


X 
X 
X 
X 


X X X 
X 
X 
X X X 
X X X 
X X X 
X X X 
X X X 
X 
X X 
X X 
X 
X 
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c- 


Decrement Date (DECD) 


Op Code (Hex) 


0414 


Operand 1: 
Operand 2: 
Operand 3: 


Operand 4: 


Operand 2 
Source date 


Operand 1 
Result date 


Character variable scalar. 


Character scalar. 


Packed decimal scalar. 


Space pointer. 


ILE access 


DECD ( 


var result_date 
var source date 
var duration 


instruction template : 


: aggregate; 

: aggregate; 

: packed decimal; 
space pointer 


Decrement Date (DECD) 


Operand 4 
Instruction template 


Description: The date specified by operand 2 is decremented by the date duration specified by 
operand 3. The resulting date from the operation is placed in operand 1. Operand 4 defines the data 
definitional attributes for operands 1 through 3. 


The following describes the instruction template. 


e Instruction template 


— Instruction template size 


— QOperand 1 data definitional attribute template number 


— Operand 2 data definitional attribute template number 


— Operand 3 data definitional attribute template number 


— OQOperand 1 length 


— Operand 2 length 


— QOperand 3 length 


- Fractional number of digits 


- Total number of digits 


— Input indicators 


0 
4 


0: = 
4 = 


- End of month adjustment 


No adjustment 


Adjustment 


- Tolerate data decimal errors 


No toleration 


Tolerate 


- Reserved (binary 0) 


— OQutput indicators 


Char(*) 
Bin(4) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(1) 
Char(1) 
Char(2) 
Bit O 


Bit 1 


Bit 2-15 


Char(2) 
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- End of month adjustment Bit 0 
0 = No adjustment 
1 = Adjustment 
- Reserved (binary 0) Bit 1-15 
— Reserved (binary 0) Char(22) 
— Data definitional attribute template list Char(*) 
- Size of the DDAT list UBin(4) 
- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute template list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


The DDATs for operands 1 and 2 must be valid for a date and identical. The DDAT for operand 3 must 
be valid for a date duration. Otherwise, a template value invalid (hex 3801) exception will be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


The input indicator, end of month adjustment, is used to allow or disallow the occurrence of an end of 
month adjustment. 


The input indicator, tolerate decimal data errors, is used to determine whether errors found in the 
packed data for the duration will generate exceptions or will be ignored. When the errors are to be 
tolerated, the following rules will apply: 


1. An invalid sign nibble found in the packed data value will be changed to a hex F. 
2. Any invalid decimal digits found in the packed data value will be forced to zero. 


3. If all digits of a packed data value become Zero, and no decimal overflow condition exists, the sign 
will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will 
not be changed, but its representation will be changed to the preferred sign code. 


The output indicator, end of month adjustment, is used to indicate an end of month adjustment, when 
end of month adjustments are allowed. 


End of month adjustment is the following concept. For SAA, the result of subtracting a 1 month dura- 
tion from the Gregorian date 03/31/1989 is 02/28/1989. The days portion is adjusted to fit the month, 31 
is changed to 28. When this happens, the end of month adjustment output indicator is set to on. 


When end of month adjustments are not allowed, the month and year definitions in the data definition 
attribute template must have values greater than Zero, otherwise a template value invalid (hex 3801) 
exception will be signalled. The result of subtracting a 1 month duration from the Gregorian date 
03/31/1989 is 03/01/1989, when the definition of a month is 30 days. 


The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 3. 
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The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes 
definitional attributes of the operands. The length of the date and date duration character operands will 


be defined by the template. For a further description of the data definitional attribute template, see 
“Data Definitional Attribute Template” on page 3-5. 


Authorization Required 


None. 


Lock Enforcement 


None. 


Exceptions 


Exception 


06 


08 


0c 


20 


22 


24 


Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range ; 

06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Computation 

02 Decimal data 

15 Date boundary overflow 
16 Data format 

17 Data value 


18 Date boundary underflow 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Operands 
1 2 3 4 Other 


x K KK 
x Km KK 
x KK OK 
x K K XK 


X 
X X 
X 
X 
X X 
X X X X 
X X X X 


x< 
x< 
x< 
rad 
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Exception 
2E Resource Control Limit 


01 User Profile storage limit exceeded 


32 Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


36 Space Management 


01 Space Extension/Truncation 


38 Template Specification 


01 Template value invalid 


Decrement Date (DECD) 


Operands 
1 2 3 4 Other 


X 
Xx X 
X X 
X 
X 
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Decrement Time (DECT) 


Op Code (Hex) Operand 1 
0444 Result time 


Operand 4 
Instruction template 


Operand 3 
Duration 


Operand 2 
Source time 


Operand ?: Character variable scalar. 
Operand 2: Character scalar. 
Operand 3: Packed decimal scalar. 


Operand 4: Space pointer. 


ILE access 


DECT ( 

var result_time 

var source time : aggregate; 

var duration : packed decimal; 
instruction template : space pointer 


: aggregate; 


Description: The time specified by operand 2 is decremented by the time duration specified by 
operand 3. The resulting time from the operation is placed in operand 1. Operand 4 defines the data 
definitional attributes for operands 1 through 3. 


The following describes the instruction template. 


e Instruction template Char(*) 
— Instruction template size Bin(4) 
— Operand 1 data definitional attribute template number UBin(2) 
— Operand 2 data definitional attribute template number UBin(2) 
— Operand 3 data definitional attribute template number UBin(2) 
— Operand 1 length UBin(2) 
— Operand 2 length UBin(2) 
— Operand 3 length UBin(2) 

- Fractional number of digits Char(1) 
- Total number of digits Char(1) 
— Input indicators Char(2) 
- Reserved (binary 0) Bit O 
- Tolerate data decimal errors Bit 1 
0 = No toleration 
1 = Tolerate 
- Reserved (binary 0) Bit 2-15 
— Reserved (binary 0) Char(24) 
— Data definitional attribute template list Char(*) 
- Size of the DDAT list UBin(4) 
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- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) J 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute template list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


The DDATs for operands 1 and 2 must be valid for a time and identical. The DDAT for operand 3 must 
be valid for a time duration. Otherwise, a template value invalid (hex 3801) exception will be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


The input indicator, tolerate decimal data errors, is used to determine whether errors found in the 
packed data for the duration will generate exceptions or will be ignored. When the errors are to be 
tolerated, the following rules will apply: 


1. An invalid sign nibble found in the packed data value will be changed to a hex F. 
2. Any invalid decimal digits found in the packed data value will be forced to zero. 


3. If all digits of a packed data value become Zero, and no decimal overflow condition exists, the sign 
will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will 
not be changed, but its representation will be changed to the preferred sign code. 


The size of the DDAT list is specified in bytes. 


. 
The number of DDATs is the count of DDATs specified for this instruction template. The maximum @ 
number of DDATs that can be specified is 3. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the time and time duration character operands will 
be defined by the templates. For a further description of the data definitional attribute template, see 
“Data Definitional Attribute Template” on page 3-5. 


Authorization Required 


e None. 


Lock Enforcement 


« None. 
Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 2 


03 Range xX xX X X 
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Exception 


08 


le 


10 


20 


22 


24 


2E 


32 


36 


38 


06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Computation 
02 Decimal data 
16 Data format 


17 Data value 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 


01 Template value invalid 


Decrement Time (DECT) 


Operands 
1 2 
X X X X 


w 
f- 


Other 


X 
X 
X X X X 
X X X X 
X X X X 
X X X X 
X X X X 
X 
X X 
X X 
X 
X 
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Decrement Timestamp (DECTS) 


Decrement Timestamp (DECTS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
042C Result timestamp Source timestamp Duration Instruction template 


Operand f: Character variable scalar. 
Operand 2: Character scalar. 
Operand 3: Packed decimal scalar. 


Operand 4: Space pointer. 


ILE access 
DECTS ( 
var result_timestamp : aggregate; 
var source_timestamp : aggregate; 
var duration : packed decimal; 


instruction template : space pointer 


Description: The timestamp specified by operand 2 is decremented by the date, time, or timestamp 
duration specified by operand 3. The resulting timestamp from the operation is placed in operand 1. 
Operand 4 defines the data definitional attributes for operands 1 through 3. 


The following describes the instruction template. 


e Instruction template Char(*) 
— Instruction template size Bin(4) 
— Operand 1 data definitional attribute template number UBin(2) 
— Operand 2 data definitional attribute template number UBin(2) 
— Operand 3 data definitional attribute template number UBin(2) 
— Operand 1 length UBin(2) 
— Operand 2 length UBin(2) 
— OQOperand 3 length UBin(2) 
- Fractional number of digits Char(‘) 
- Total number of digits Char(1) 

— Input indicators Char(2) 
- End of month adjustment Bit 0 


O = No adjustment 


1 = Adjustment 


- Tolerate data decimal errors Bit 1 
0 = No toleration 
1 = Tolerate 
- Reserved (binary 0) Bit 2-15 
— Output indicators Char(2) 
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- End of month adjustment Bit O 
0 = No adjustment 
1 = Adjustment 
- Reserved (binary 0) Bit 1-15 
— Reserved (binary 0) Char(22) 
— Data definitional attribute template list Char(*) 
- Size of the DDAT list UBin(4) 
- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute tempiate list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


The DDATs for operands 1 and 2 must be valid for a timestamp and identical. The DDAT for operand 3 
must be valid for a timestamp duration. Otherwise, a template value invalid (hex 3801) exception will 
be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


The input indicator, end of month adjustment, is used to allow or disallow the occurrence of an end of 
month adjustment. 


The input indicator, tolerate decimal data errors, is used to determine whether errors found in the 
packed data for the duration will generate exceptions or will be ignored. When the errors are to be 
tolerated, the following rules will apply: 


1. An invalid sign nibble found in the packed data value will be changed to a hex F. 
2. Any invalid decimal digits found in the packed data value will be forced to zero. 


3. If all digits of a packed data value become Zero, and no decimal overflow condition exists, the sign 
will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will 
not be changed, but its representation will be changed to the preferred sign code. 


The output indicator, end of month adjustment, is used to indicate an end of month adjustment, when 
end of month adjustments are allowed. . 


End of month adjustment is the following concept. For SAA, the result of subtracting a 1 month dura- 
tion from the date 03/31/1989 is 02/28/1989. The days portion is adjusted to fit the month, 31 is changed 
to 28. When this happens, the end of month adjustment output indicator is set to on. 


When end of month adjustments are not allowed, the month and year definitions in the data definition 
attribute template must have values greater than zero, otherwise a template value invalid (hex 3801) 
exception will be signaled. The result of subtracting a 1 month duration from the Gregorian date 
03/31/1989 is 03/01/1989, when the definition of a month is 30 days. 


The size of the DDAT list is specified in bytes. 
The number of DDATs is the count of DDATs specified for this instruction template. The maximum 


number of DDATs that can be specified is 3. 


Chapter 3. Date/Time/Timestamp Instructions 3-39 


The DDAT offset 
is the number of bytes from the start of the DDAT list to the start of the specific DDAT. There should 


be as many DDAT offsets as there are DDATs Specified. 


Decrement Timestamp (DECTS) 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the timestamp and duration character operands 
will be defined by the template. For a further description of the data definitional attribute template, see 


“Data Definitional Attribute Template” on page 3-5. 


Authorization Required 


None. 


Lock Enforcement 


None. 


Exceptions 


Exception 


06 


08 


0c 


10 


20 


22 


24 


Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Computation 

02 Decimal data 

15 Date boundary overflow 
16 Data format 

17 Data value 


18 Date boundary underflow 


Damage Encountered 
04 System object damage state 
44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 


01 Pointer does not exist 


Other 


— 
NO 
aw 
= 


x KK OK 
x XK * x 
x KX K XK 
x KK K 


x K K XK 


x 
x< 
x< 
x 
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Decrement Timestamp (DECTS) 


Operands 

Exception 1 2 3 4 Other 

02 Pointer type invalid X X X X 
2E Resource Control Limit 

01 User Profile storage limit exceeded X 
32 Scalar Specification 

02 Scalar attributes invalid X X 

03 Scalar vaiue invalid X X 
36 Space Management 

01 Space Extension/Truncation X 
38 Template Specification 

01 Template value invalid X 
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Op Code (Hex) . Operand 1 Operand 2 


0404 


Result date Source date 


Operand 7: Character variable scalar. 


Operand 2: Character scalar. 


Operand 3: Packed decimal scalar. 


Operand 4. Space pointer. 


ILE access 
INCD ( 
var result _date : aggregate; 
var source date : aggregate; 
var duration : packed decimal; 


instruction template : space pointer 


Increment Date (INCD) 


e) 


Operand 3 Operand 4 


Duration 


Instruction template 


Description: The date specified by operand 2 is incremented by the date duration specified by 
operand 3. The resulting date from the operation is placed in operand 1. Operand 4 defines the data 
definitional attributes for operands 1 through 3. 


The following describes the instruction template. 


¢ Instruction template 


Instruction template size 
Operand 1 data definitional attribute template number 
Operand 2 data definitional attribute template number 
Operand 3 data definitional attribute template number 
Operand 1 length 
Operand 2 length 
Operand 3 length 
- Fractional number of digits 
- Total number of digits 
Input indicators 
- End of month adjustment 
0 = No adjustment 
1 = Adjustment 
- Tolerate data decimal errors 
0 
1 
- Reserved (binary 0) 


No toleration 


Tolerate 


Output indicators 


Char(*) 
Bin(4) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(1) 
Char(1) 
Char(2) 
Bit 0 


Bit 1 


Bit 2-15 


Char(2) 
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- End of month adjustment Bit O 
O = No adjustment 


1 = Adjustment 


- Reserved (binary Q) Bit 1-15 
— Reserved (binary 0) Char(22) 
— Data definitional attribute template list Char(*) 
- Size of the DDAT list UBin(4) 
- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute template list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


The DDATs for operands 1 and 2 must be valid for a date and identical. The DDAT for operand 3 must 
be valid for a date duration. Otherwise, a template value invalid (hex 3801) exception will be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


The input indicator, end of month adjustment, is used to allow or disallow the occurrence of an end of 
month adjustment. 


The input indicator, tolerate decimal data errors, is used to determine whether errors found in the 
packed data for the duration will generate exceptions or will be ignored. When the errors are to be 
tolerated, the following rules will apply: 


1. An invalid sign nibble found in the packed data value will be changed to a hex F. 
2. Any invalid decimal digits found in the packed data value will be forced to zero. 


3. If all digits of a packed data value become zero, and no decimal overflow condition exists, the sign 
will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will 
not be changed, but its representation will be changed to the preferred sign code. 


The output indicator, end of month adjustment, is used to indicate an end of month adjustment, when 
end of month adjustments are allowed. 


End of month adjustment is the following concept. For SAA, the result of adding a 1 month duration to 
the date 01/31/1989 is 02/28/1989. The days portion is adjusted to fit the month, 31 is changed to 28. 
When this happens,the end of month adjustment output indicator is set to on. 


When end of month adjustments are not allowed, the month and year definitions in the data definition 
attribute template must have values greater than zero, otherwise a template value invalid (hex 3801) 
exception will be signaled. The result of adding a 1 month duration to the Gregorian date 01/31/1989 is 
03/02/1989, when the definition of a month is 30 days. 


The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 3. 
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The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes 
definitional attributes of the operands. The length of the date and date duration character operands will 
be defined by the template. For a further description of the data definitional attribute template, see 


“Data Definitional Attribute Template” on page 3-5. 


Authorization Required 


None. 


Lock Enforcement 


None. 


Exceptions 


Exception 


06 


08 


0c 


10 


20 


22 


24 


Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Computation 

02 Decimal data 

15 Date boundary overflow 
16 Data format 

17 Data value 


18 Date boundary underflow 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 
03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Operands 
1 2 3 4 Other 


x «~~ K KK 
x KK OK 
x KK XK 
x KK OK 


<x K KK XK 


x< 
x< 
x< 
< 
x< 


< 
»< 
*< 
~< 
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Exception 


2E 


32 


36 


38 


Resource Control Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 


01 Template value invalid 


Increment Date (INCD) 


Operands 
1 2 3 4 Other 


X 
X X 
X X 
X 
X 
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Op Code 
0434 


(Hex) Operand 1 Operand 2 
Result time Source time 


Operand ?: Character variable scalar. 


Operand 2: Character scalar. 


Operand 3: Packed decimal scalar. 


Operand 4: Space pointer. 


ILE access 
INCT ( 
var result_time : aggregate; 
var source time : aggregate; 
var duration : packed decimal; 


i 


nstruction template : space pointer 


Increment Time (INCT) 


J 


Operand 3 Operand 4 
Duration instruction template 


Description: The time specified by operand 2 is incremented by the time duration specified by 
operand 3. The resulting time from the operation is placed in operand 1. Operand 4 defines the data 


definitio 


nal attributes for operands 1 through 3. 


The following describes the instruction template. 


e Instruction template 


Instruction template size 
Operand 1 data definitional attribute template number 
Operand 2 data definitional attribute template number 
Operand 3 data definitional attribute template number 
Operand 1 length 
Operand 2 length 
Operand 3 length 
- Fractional number of digits 
- Total number of digits 
Input indicators 
- Reserved (binary 0) 
- Tolerate data decimal errors 
0 = No toleration 
1 = Tolerate 
- Reserved (binary 0) 
Reserved (binary 0) 
Data definitional attribute template list 
- Size of the DDAT list 


Char(*) 
Bin(4) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(‘1) 
Char(1) 
Char(2) 
Bit O 
Bit 1 


Bit 2-15 


Char(24) 2 


Char(*) 
UBin(4) 
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- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 


A data definitional attribute template number (DDAT) is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute template list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


The DDATs for operands 1 and 2 must be valid for a time and identical. The DDAT for operand 3 must 
be valid for a time duration. Otherwise, a template value invalid (hex 3801) exception will be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


The input indicator, tolerate decimal data errors, is used to determine whether errors found in the 
packed data for the duration will generate exceptions or will be ignored. When the errors are to be 
tolerated, the following rules will apply: 


1. An invalid sign nibble found in the packed data value will be changed to a hex F. 
2. Any invalid decimal digits found in the packed data value will be forced to zero. 


3. If all digits of a packed data value become zero, and no decimal overflow condition exists, the sign 
will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will 
not be changed, but its representation will be changed to the preferred sign code. 


The size of the DDAT list is specified in bytes. 


The number of DDATs is the count of DDATs specified for this instruction template. The maximum 
number of DDATs that can be specified is 3. 


The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the time and time duration character operands will 
be defined by the templates. For a further description of the data definitional attribute template, see 
“Data Definitional Attribute Template” on page 3-5. 


Authorization Required 


¢ None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 

Exception 1 2 3 4 Other 
06 Addressing 

01 Space addressing violation X X Xx X 

02 Boundary alignment X X X X 

03 Range X X Xx X 
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Exception 


08 


OC 


20 


22 


24 


2E 


32 


36 


38 


06 Optimized addressability invalid 


Argument/Parameter 


01 Parameter reference violation 


Computation 
02 Decimal data 
16 Data format 


17 Data value 


Damage Encountered 
04 System object damage state 


44 Partial system object damage 


Machine Support 
02 Machine check 


03 Function check 


Object Access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


Pointer Specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource Control! Limit 


01 User Profile storage limit exceeded 


Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 


01 Template value invalid 


Increment Time (INCT) 


Operands 
1 2 
X X X X 


Other 


& 
Pp 


x 
x 
x << x -x 
Xx xX xX xX 
x x - & 
x MM. Ke 
Xx xX xX xX 
x 
x x 
x x 
x 
x 
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Increment Timestamp (INCTS) 


Increment Timestamp (INCTS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
040C Result timestamp Source timestamp Duration Instruction template 


Operand 1: Character variable scalar. 
Operand 2: Character scalar. 
Operand 3: Packed decimal scalar. 


Operand 4: Space pointer. 


ILE access 
INCTS ( 
var result_timestamp : aggregate; 
var source timestamp : aggregate; 
var duration : packed decimal; 


instruction template : space pointer 


Description: The timestamp specified by operand 2 is incremented by the date, time, or timestamp 
duration specified by operand 3. The resulting timestamp from the operation is placed in operand 1. 
Operand 4 defines the data definitional attributes for operands 1 through 3. 


The following describes the instruction template. 


e Instruction template Char(*) 
— Instruction template size Bin(4) 
— OQOperand 1 data definitional attribute template number UBin(2) 
— Operand 2 data definitional! attribute template number UBin(2) 
— Operand 3 data definitional attribute template number UBin(2) 
— Operand 1 length UBin(2) 
— Operand 2 length UBin(2) 
— Operand 3 length UBin(2) 

- Fractional number of digits Char(1) 
- Total number of digits Char(1) 
— Input indicators Char(2) 
- End of month adjustment Bit O 
0 = No adjustment 
= Adjustment 
- Tolerate data decimal errors Bit 1 


0 = No toleration 
1 = Tolerate 
- Reserved (binary 0) Bit 2-15 
— Output indicators Char(2) 
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- End of month adjustment Bit 0 
0 = No adjustment 


1 = Adjustment 


- Reserved (binary 0) Bit 1-15 
— Reserved (binary 0) Char(22) 
— Data definitional attribute template list Char(*) 
- Size of the DDAT list UBin(4) 
- Number of DDATs UBin(2) 
- Reserved (binary 0) Char(10) 
- DDAT offset (repeated) UBin(4) 
- Data definitional attribute template (repeated) Char(*) 


A data definitional attribute template (DDAT) number is a number that corresponds to the relative posi- 
tion of a template in the data definitional attribute template list. For example the number 1 references 


the first template. The valid values for this field are 1, 2, and 3. 


The DDATs for operands 1 and 2 must be valid for a ttmestamp and identical. The DDAT for operand 3 
must be valid for a timestamp duration. Otherwise, a template value invalid (hex 3801) exception will 
be issued. 


Operand 1 length and operand 2 length are specified in number of bytes. 


The input indicator, end of month adjustment, is used to allow or disallow the occurrence of an end of 
month adjustment. 


The input indicator, tolerate decimal data errors, is used to determine whether errors found in the 
packed data for the duration will generate exceptions or will be ignored. When the errors are to be 
tolerated, the following rules will apply: 


1. An invalid sign nibble found in the packed data value will be changed to a hex F. 
2. Any invalid decimal digits found in the packed data value will be forced to zero. 


3. If all digits of a packed data value become Zero, and no decimal overflow condition exists, the sign 
will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will 
not be changed, but its representation will be changed to the preferred sign code. 


The output indicator, end of month adjustment, is used to indicate an end of month adjustment, when 
end of month adjustments are allowed. 


End of month adjustment is the following concept. For SAA, the result of adding a 1 month duration to 
the date 01/31/1989 is 02/28/1989. The days portion is adjusted to fit the month, 31 is changed to 28. 
When this happens, the end of month adjustment output indicator is set to on. 


When end of month adjustments are not allowed, the month and year definitions in the data definition 
attribute template must have values greater than zero, otherwise a template value invalid (hex 3801) 
exception will be signaled. The result of adding a 1 month duration to the Gregorian date 01/31/1989 is 
03/02/1989, when the definition of a month is 30 days. 


The size of the DDAT list is specified in bytes. 
The number of DDATs is the count of DDATs specified for this instruction template. The maximum 


number of DDATs that can be specified is 3. 
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The DDAT offset is the number of bytes from the start of the DDAT list to the start of the specific DDAT. 
There should be as many DDAT offsets as there are DDATs specified. 


A data definitional attribute template defines the presentation of the data. Each template describes the 
definitional attributes of the operands. The length of the timestamp and duration character operands 
will be defined by the template. For a further description of the data definitional attribute template, see 
“Data Definitional Attribute Template” on page 3-5. 


Authorization Required 


e None. 


Lock Enforcement 


e None. 
Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range ; X X X X 
06 Optimized addressability invalid X X X X 
08 Argument/Parameter 
01 Parameter reference violation X X X X 
0c Computation 
02 Decimal data X 
15 Date boundary overfiow X X 
16 Data format X 
17 Data value X 
18 Date boundary underflow X X 
10 Damage Encountered 
04 System object damage state X X X X X 
44 Partial system object damage _ X X X X X 
20 Machine Support 
02 Machine check X 
03 Function check X 
22 Object Access 
01 Object not found X X X X 
02 Object destroyed X X X X 
03 Object suspended Xx X X X 
24 Pointer Specification 
01 Pointer does not exist xX Xx X X 
02 Pointer type invalid X xX X X 
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Exception 
2E Resource Control Limit 


01 User Profile storage limit exceeded 


32 Scalar Specification 
02 Scalar attributes invalid 


03 Scalar value invalid 


36 Space Management 


01 Space Extension/Truncation 


38 Template Specification 


01 Template value invalid 


Increment Timestamp (INCTS) 


Operands 
1 2 3 4 Other 
X 
X X 
X X 
X 
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Chapter 4. Pointer/Name Resolution Addressing Instructions 


This chapter describes the instructions used for pointer and name resolution functions. These 
instructions are in alphabetic order. See Appendix A, “Instruction Summary,” for an alphabetic 
summary of ail the instructions. 


Compare Pointer for Object Addressability (CMPPTRA) ..........0...0.0. 0000000 eee 4-3 
Compare Pointer for Space Addressability (CMPPSPAD) .................. 02.0004 4-5 
Compare Pointers for Equality (CMPPTRE) ..........0 00.00. 0c 4-7 
Compare Pointer Type (CMPPTRT) ........0 0... 0c ee 4-9 
Copy Bytes with Pointers (CPYBWP) ......... 0.000... 000 ee 4-12 
Resolve Data Pointer (RSLVDP) ..... 0... 0. cc ee 4-14 
Resolve System Pointer (RSLVSP) .......0 00.00.00. 0c ee 4-17 
Set Space Pointer from Pointer (SETSPPFP) ..........0.0 000.00 eee ee ee es 4-22 
Set System Pointer from Pointer (SETSPFP) .......... 0.0.0. 00 eee ee ee ee 4-24 
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Compare Pointer for Object Addressability (CMPPTRA) 


Compare Pointer for Object Addressability (CMPPTRA) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 [4] 
CMPPTRAB Branch options Compare Compare Branch targets 
1CD2 operand 1 operand 2 

CMPPTRAI Indicator options Compare Compare Indicator targets 
18D2 operand 1 operand 2 


Operand ?: Data pointer, space pointer, system pointer, or instruction pointer. 
Operand 2: Data pointer, space pointer, system pointer, or instruction pointer. 


Operand 3 [4]: 
e Branch Form —Instruction number, relative instruction number, branch point, or instruction pointer. 
e Indicator Form—Numeric variable scalar or character variable scalar. 
Description: The object addressed by operand 1 is compared with the object addressed by operand 2 
to determine if both operands are addressing the same object. Based on the comparison, the resulting 


condition is used with the extender to transfer control (branch form) or to assign a value to each of the 
indicator operands (indicator form). 


lf operand 1 is a data pointer, a space pointer, or a system pointer, operand 2 may be any pointer type 
except for instruction pointer in any combination. An equal! condition occurs if the pointers are 
addressing the same object. For space pointers and data pointers, only the space they are addressing 
is considered in the comparison. That is, the space offset portion of the pointer is ignored. 


For system pointer compare operands, an equal condition occurs if the system pointer is compared 
with a space pointer or data pointer that addresses the space that is associated with the object that is 
addressed by the system pointer. For example, a space pointer that addresses a byte in a space asso- 
ciated with a system object compares equal with a system pointer that addresses the system object. 


For instruction pointer comparisons, both operands must be instruction pointers; otherwise, an invalid 
pointer type (hex 2402) exception is signaled. An equa/ condition occurs when both instruction pointers 
are addressing the same instruction in the same program. A not equal condition occurs if the instruc- 
tion pointers are not addressing the same instruction in the same program. 


A pointer does not exist (hex 2401) exception is signaled if a pointer does not exist in either of the 
operands. 
Resultant Conditions 

e Equal 


e Not equal 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 


Chapter 4. Pointer/Name Resolution Addressing Instructions 4-3 


Compare Pointer for Object Addressability (CMPPTRA) 


Exceptions 
Operands wa 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range X X X X 
06 Optimized addressability invalid X X X Xx 
08 Argument/parameter 
01 Parameter reference violation X X X X 
0A Authorization 
01 Unauthorized for operation X X 
10 Damage encountered 
04 System object damage state X X X X X 
05 authority verification terminated due to damaged object X 
44 Partial system object damage X xX X X X 
1A Lock state 
01 Invalid lock state X xX’ 
1c Machine-dependent exception : 
03 Machine storage limit exceeded X J 
20 Machine support 
02 Machine check X 
03 Function check X 
22 Object access 
01 Object not found X X X X 
02 Object destroyed X X X X 
03 Object suspended X X X X 
07 authority verification terminated due to destroyed object X 
08 object compressed X 
24 Pointer specification 
01 Pointer does not exist X X X X 
02 Pointer type invalid X X X X 
2E Resource control limit 
01 user profile storage limit exceeded X 
36 Space management 
01 space extension/truncation X 
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Compare Pointer. for Space Addressability (CMPPSPAD) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 [4-6] 
CMPPSPADB Branch options Compare Compare Branch targets 
1CE6 Operand 1 Operand 2 

CMPPSPADI Indicator options Compare Compare Indicator targets 
18E6 Operand 1 Operand 2 


Operand ?: Space pointer or data pointer. 


Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character vari- 
able array, space pointer, or data pointer. 


Operand 3 [4-6]: 
e Branch Form-|nstruction number, relative instruction number, branch point, or instruction pointer. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The space addressability contained in the pointer specified by operand 1 is compared 
with the space addressability defined by operand 2. 


The value of the operand 1 pointer is compared based on the following: 


e If operand 2 is a scalar data object (element or array), the space addressability of that data object 
is compared with the space addressability contained in the operand 1 pointer. 


e lf operand 2 is a pointer, it must be a space pointer or data pointer, and the space addressability 
contained in the pointer is compared with the space addressability contained in the operand 1 
pointer. 


Based on the results of the comparison, the resulting condition is used with the extender to transfer 
control (branch form) or to assign a value to each of the indicator operands (indicator form). If the 
operands are not in the same space, the resultant condition is unequal. If the operands are in the 
same space and the offset into the space of operand 1 is larger or smaller than the offset of operand 2, 
the resultant condition is high or low, respectively. An equa/ condition occurs only if the operands are 
in the same space at the same offset. Therefore, the resultant conditions (high, low, equal, and 
unequal) are mutually exclusive. Consequently, if you specify that an action be taken upon the nonex- 
istence of a condition, this results in the action being taken upon the occurrence of any of the other 
three possible conditions. For example, a branch not high would result in the branch being taken on a 
low, equal, or unequal condition. 


The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, 
parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are 
not signaled when operand 1 or operand 2 is a space pointer machine object or when operand 2 is a 
scalar based on a space pointer machine object. This occurs when the space pointer machine object 
contains an internal machine value that indicates one of these error conditions exists. If the corre- 
sponding exception is not signaled, the resulting condition of the comparison operation is not defined 
other than that it will be one of the four valid resultant conditions for this instruction. 


When the Override Program Attributes (OVRPGATR) instruction is used to override this instruction, the 
pointer does not exist, (hex 2401) exception is not signaled when operand 1 or operand 2 is a space 
pointer (i.e. either a space pointer data object or a space pointer machine object). Furthermore, some 
comparisons involving space pointers are defined even when one or both of the compare operands is 
a pointer subject to the pointer does not exist condition. Specifically, if both compare operands are 
subject to the pointer does not exist condition, the resultant condition is equa/. When one space 
pointer is set and one is subject to the pointer does not exist condition, the resultant condition is 
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Compare Pointer for Space Addressability (CMPPSPAD) 


unequal, but undefined with respect to comparisons which include specification of the high or low con- 


ditions. 2 


Resultant Conditions 


¢ High 
¢ Low 
e Equal 
e Unequal 
Exceptions 
Operands 
Exception 1 2 3 [4-6] Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X 
03 range X X 
04 external data object not found X X 
06 optimized addressability invalid X X 
08 Argument/parameter 
01 parameter reference violation X X 
10 Damage encountered F 
04 system object damage state X X X X 2 
44 partial system object damage X X X X 
1c Machine-dependent exception 
03 machine storage limit exceeded X 
20 Machine support 
02 machine check X 
03 function check X 
22 Object access 
01 object not found X X X 
02 object destroyed X X X 
03 object suspended X X X 
08 object compressed X 
24 Pointer specification 
01 pointer does not exist xX X X 
02 pointer type invalid X X X 
2E Resource control limit 
01 user profile storage limit exceeded X 
36 Space management | 3 
01 space extension/truncation X 
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Compare Pointers for Equality (CMPPTRE) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 [4] 
CMPPTREB Branch options Compare Compare Branch targets 
1012 operand 1 operand 2 

CMPPTREI Indicator options Compare Compare Indicator targets 
1812 operand 1 operand 2 


Operand 1: Data pointer, space pointer, system pointer, instruction pointer, invocation pointer, proce- 
dure pointer, label pointer, or suspend pointer 


Operand 2: Data pointer, space pointer, system pointer, instruction pointer, invocation pointer, proce- 
dure pointer, label pointer, or suspend pointer 


Operand 3 [4]: 
e Branch Form—\nstruction number, relative instruction number, branch point, or instruction pointer. 


e Indicator Form—Numeric variable scalar or character variable scalar. 


Description: The pointer specified by operand 1 is compared with the pointer specified by operand 2 
to determine if both operands are of the same type and contain equal values. Based on the compar- 
ison, the resulting condition is used with the extender to transfer control (branch form) or to assign a 
value to each of the indicator operands (indicator form). 


Pointers may be specified for operands 1 and 2 in any combination. An equal condition occurs if the 
pointers are of the same type and contain the same value, or if neither pointer has been set. If one 
pointer is set and the other is not, a not equa/ condition occurs. 


System pointers and data pointers are not resolved by this instruction. The comparison result is unde- 
fined when an unresolved pointer is supplied for one or both operands. 


Note that any authorities stored in a resolved system pointer are part of the pointer. Thus system 
pointers pointing to the same object, but with different levels of authority, will compare as not equal. 


Since any pointer type may be specified for this instruction, the invalid pointer type (hex 2402) excep- 
tion is not signaled except for pointers used as a base for the operands. Similarly, since the instruc- 
tion accepts unset pointers, the pojnter does not exist (hex 2401) exception is not signaled except for 
pointers used as a base for the operands. 


Resultant Conditions 


e Equal 
e Not equal 
Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range X X X X 
06 Optimized addressability invalid X X X X 
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Compare Pointers for Equality (CMPPTRE) 


Exception 


08 


0A 


1A 


1c 


20 


22 


24 


2E 


36 


Argument/parameter 


01 Parameter reference violation 


Authorization 


01 Unauthorized for operation 


Damage encountered 
04 System object damage state 
05 authority verification terminated due to damaged object 


44 Partial system object damage 


Lock state 


01 Invalid lock state 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 

03 Object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 


~< 


~< 


Other 


~*~ 
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Compare Pointer Type (CMPPTRT) 


Compare Pointer Type (CMPPTRT) 


© Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 [4] 
CMPPTRTB Branch options Compare Compare Branch targets 
1CE2 operand 1 operand 2 
CMPPTRTI Indicator options Compare Compare Indicator targets 
18E2 operand 1 operand 2 


| Operand 7: Data pointer, space pointer, system pointer, instruction pointer, invocation pointer, proce- 
| dure pointer, label pointer, or suspend pointer 


Operand 2: Character(1) scalar or null. 
Operand 3 [4]: 


¢ Branch Form-—lInstruction number, relative instruction number, branch point, or instruction pointer. 


¢ /ndicator Form—Numeric variable scalar or character variable scalar. 


Extender 


Description: The instruction compares the pointer type currently in operand 1 with the character 
scalar identified by operand 2. Based on the comparison, the resulting condition is used with the 
extender to transfer control (branch form) or to assign a value to each of the’ indicator operands (indi- 
cator form). 


Operand 1 can specify a space pointer machine object only when operand 2 is null. 


lf operand 2 is null or if operand 2 specifies a comparison value of hex 00, an equal condition occurs if 
a pointer does not exist in the storage area identified by operand 1. 


Following are the allowable values for operand 2: 


Hex 00 — A pointer does not exist at this location 
Hex 01 — System pointer 
Hex 02 — Space pointer 
Hex 03 — Data pointer 
Hex 04 — Instruction pointer 
| Hex 05 — Invocation pointer 
| Hex 06 — Procedure pointer 
| Hex 07 — Label pointer 
| Hex 08 — Suspend pointer 


Resultant Conditions 
e Equal 


e Not equal 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


< 
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Compare Pointer Type (CMPPTRT) 


Lock Enforcement 


¢ Materialize J 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation 
02 Boundary alignment 
03 Range 


x KK K 
x KK K 
x KK 
x KK OK 


06 Optimized addressability invalid 


08 Argument/parameter 


01 Parameter reference violation 4 xX 4 xX 


0A Authorization 


01 Unauthorized for operation X 


10 Damage encountered 
04 System object damage state X x X X X 


x 


05 authority verification terminated due to damaged object 
44 Partial system object damage X X X X X ) 


1A Lock state 
01 Invalid lock state X 


1C Machine-dependent exception 


03 Machine storage limit exceeded X 


20 Machine support 
02 Machine check X 
03 Function check xX 


22 Object access 
01 Object not found X X X X 
02 Object destroyed 
03 Object suspended X Xx Xx X 
07 authority verification terminated due to destroyed object X 


x 
< 
*< 
< 


08 object compressed X 


24 Pointer specification 
01 Pointer does not exist Xx X X X 
02 Pointer type invalid X X X X 


2E Resource control Jimit 


01 user profile storage limit exceeded X 


32 Scalar specification 


03 Scalar value invalid X 
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Compare Pointer Type (CMPPTRT) 


Operands 
Exception 1 2 3 4 Other 
: 36 Space management 
01 space extension/truncation Xx 
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Copy Bytes with Pointers (CPYBWP) 


Op Code (Hex) Operand 1 Operand 2 
0132 Receiver Source 


Operand 1: Character variable scalar, space pointer, data pointer, system pointer, instruction pointer. 
invocation pointer, procedure pointer, label pointer, or suspend pointer 


Operand 2: Character variable scalar, space pointer, data pointer, system pointer, instruction pointer, 
invocation pointer, procedure pointer, label pointer, suspend pointer, or null 


Description: This instruction copies either the pointer value or the byte string specified for the source 
operand into the receiver operand depending upon whether or not a space pointer machine object is 
specified as one of the operands. 


If either operand is a character variable scalar, it can have a length as great as 16776191 bytes. 


Operations involving space pointer machine objects perform a pointer value copy operation for only 
Space pointer values or the pointer does not exist state. Due to this, a space pointer machine object 
may only be specified as an operand in conjunction with another pointer or a null second operand. 
The pointer does not exist state is copied from the source to the receiver pointer without signaling the 
pointer does not exist (hex 2401) exception. Source pointer data objects must either be not set or 
contain a space pointer value when being copied into a receiver space pointer machine object. 
Receiver pointer data objects will be set with either the system default pointer does not exist value or 
the space pointer value from a source space pointer machine object. 


Normal pointer alignment checking is performed on a pointer data object specified as an operand in ‘ 
conjunction with a space pointer machine object. J 


Operations not involving space pointer machine objects, those involving just data objects as operands, 
perform a byte string copy of the data for the specified operands. 


The value of the byte string specified by operand 2 is copied to the byte string specified by operand 1 
(no padding done). 


The byte string identified by operand 2 can contain the storage forms of both scalars and pointers. 
Normal pointer alignment checking is not done. 


\hen the Override Program Attributes (OVRPGATR) instruction is not used to override CPYBWP, the 
only alignment requirement is that the space addressability alignment of the two operands must be to 
the same position relative to a 16-byte multiple boundary. A boundary alignment (hex 0602) exception 
is signaled if the alignment is incorrect. The pointer attributes of any complete pointers in the source 
are preserved if they can be completely copied into the receiver. Partial pointer storage forms are 
copied into the receiver as scalar data. Scalars in the source are copied to the receiver as scalars. 


When the OVRPGATR instruction is used to override this instruction, the alignment requirement is 
removed. If the space addressability alignment of the two operands is the same relative to 16-byte mul- 
tiple boundary, then this instruction will work the same as stated above. If the space addressability 
alignment is different, then this instruction will work like a Copy Bytes Left Adjusted (CPYBLA) and the 
pointer attributes of any complete pointers in the source are not preserved in the receiver. 


lf a pointer data object operand contains a data pointer value upon execution of the instruction, the | 
pointer storage form is copied rather than the scalar described by the data pointer value. The char- a 
acter variable scalar reference allowed on either operand cannot be described through a data pointer 

value. 
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Copy Bytes with Pointers (CPYBWP) 


The length of the operation is equal to the length of the shorter of the two operands. The copying 
begins with the two operands left-adjusted and proceeds until completion of the shorter operand. 


Operand 1 can specify a space pointer machine object only when operand 2 is a space pointer or null. 


lf operand 2 is null, operand 1 must define a pointer reference; otherwise, an invalid operand type (hex 


2A06) exception is signaled by the Create Program instruction. When operand 2 is null, the pointer 


identified by operand 1 is set to the system default pointer does not exist value. 


Exceptions 


Exception 


06 


08 


10 


20 


22 


24 


2E 


36 


Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Damage encountered 
04 System object damage state 


44 Partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 
03 Object suspended 


08 object compressed 


Pointer specification 
01 Pointer does not exist 


02 Pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


X X 

X X 

X X 

X X 

X X 

X X X 

X X X 
X 
X 
X 

X X 

X Xx 

X X 
X 

X X 

X X 
X 
X 
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Resolve Data Pointer (RSLVDP) 


Resolve Data Pointer (RSLVDP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0163 Pointer for Data object iden- Program 
addressability to tification 
data object 


Operand 1: Data pointer. 
Operand 2: Character(32) scalar (fixed-length) or null. 
Operand 3: System pointer or null. 


Description: A data pointer with addressability to and the attributes of an external scalar data element 
is returned in the storage area identified by operand 1. The following describes the instruction’s func- 
tion when operand 2 is null: 


e If operand 1 does not contain a data pointer, an exception is signaled. 


e If the data pointer specified by operand 1 is not resolved and has an initial value declaration, the 
instruction resolves the data pointer to the external scalar that the initial value describes. The 
initial value defines the external scalar to be located and, optionally, defines the program in which 
it is to be located. If the program name is specified in the initial value, only that program’s acti- 
vation entry is searched for the external scalar. If no program is specified, programs associated 
with the activation entries in the current activation group in which the program is executing, are 
searched in reverse order of the activation entries, and operand 3 is ignored. The current acti- 
vation group for non-bound programs is the default activation group whose state is the same as | 
the state of the process at the time the instruction is run. J 


e lf the data pointer is currently resolved and defines an existing scalar, the instruction causes no 
operation, and no exception is signaled. 
The following describes the instruction’s function when operand 2 is not null: 


e A data pointer that is resolved to the external scalar identified by operand 2 is returned in operand 
1. Operand 2 is a 32-byte value that provides the name of the external scalar to be located. 


e Qperand 3 specifies a system pointer that identifies the program whose activation is to be 
searched for the external scalar definition. If operand 3 is null, the instruction searches all acti- 
vations in the activaction group from which the instruction is executed, starting with the most 
recent activation and continuing to the oldest. The activation under which the instruction is issued 
also participates in the search. If operand 3 is not null, the instruction searches the activation of 
the program addressed by the system pointer. 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialize 


— Contexts referenced for address resolution 


Exceptions 2 
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Exception 


06 


08 


0A 


10 


1C 


20 


22 


24 


2E 


32 


36 


Addressing 

01 Space addressing violation 
02 Boundary alignment 

03 Range 

04 External data object not found 


06 Optimized addressability invalid 


Argument/parameter 


01 Parameter reference violation 


Authorization 


01 Unauthorized for operation 


Damage encountered 
04 System object damage state 
05 authority verification terminated due to damaged object 


44 Partial system object damage 


Lock state 


01 Invalid lock state 


Machine-dependent exception 


03 Machine storage limit exceeded 


Machine support 
02 Machine check 


03 Function check 


Object access 

01 Object not found 

02 Object destroyed 

03 Object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 Pointer does not exist 
02 Pointer type invalid 


04 Pointer not resolved 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 Scalar type invalid 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space management 


Resolve Data Pointer (RSLVDP) 


Operands 
1 2 
X Xx 
X X 
X X 
X 
X X 
X X 
X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X X 
X 
X 


>< 


Other 


x 
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Resolve Data Pointer (RSLVDP) 


Operands 
Exception 1 2 3 Other 
01 space extension/truncation X ) 
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Resolve System Pointer (RSLVSP) 


Resolve System Pointer (RSLVSP) 


c Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
0164 Pointer for Object identifica- Context through Authority to be set’ 
addressability to tion and required which objects is to 
object authorization be located 


Operand f: System pointer. 
Operand 2: Character(34) scalar (fixed-length) or null. 
Operand 3: System pointer or null. 


Operand 4: Character(2) scalar (fixed-length) or null. 


| ILE access 


| | RSLVSP ( 

| var ptr_to_object : system pointer; 

| var objid_and_authreq : aggregate; OR 

| null operand; 

| var context : system pointer; OR 
| null operand; 
| var authority_to_set =: aggregate OR 
| null operand 
| 


S Description: This instruction locates an object identified by a symbolic address and stores the object’s 
addressability and authority’ in a system pointer. A resolved system pointer is returned in operand 1 
with addressability to a system object and the requested authority currently available to the process 
for the object. 


Note: The ownership flag is never set in the system pointer. 
Operand 2 specifies the symbolic identification of the object to be located. Operand 3 identifies the 
context to be searched in order to locate the object. Operand 4 identifies the authority states to be set 
in the pointer. First, the instruction locates an object based on operands 2 and 3. Then, the instruction 
sets the appropriate authority states in the system pointer. 
The following describes the instruction’s function when operand 2 is null: 

e |f operand 1 does not contain a system pointer, an exception is signaled. 


e If the system pointer specified by operand 1 is not resolved but has an initial value declaration, the 
instruction resolves the system pointer to the object that the initial value describes. The initial 
value defines the following: 


— Object to be located (by type code, subtype code, and object name) 
— Context to be searched to locate the object (optional) 
— Minimum required authorization required for the object 


If a context is specified, only that context is referenced to locate the object, and operand 3 is 
ignored. If no context is specified, the context(s) located by the process name resolution list is 


c 


1 Programs executing in user-domain may not assign authority in the resulting system pointer. The value in operand 4 is 
ignored and no exception Is raised. 
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Resolve System Pointer (RSLVSP) 


used to locate the object, and operand 3 is ignored. If the object is of a type that can only be 
addressed through the machine context, then only the machine context is searched, and the 
context (if any) identified in the initial value or identified in operand 3 is ignored. J 


If the minimum required authorization in the initial value is not set (binary 0), the instruction 
resolves the operand 1 system pointer to the first object encountered with the designated type 
code, subtype code, and object name without regard to the authorization available to the process 
for the object. If one or more authorization (or ownership) states are required (signified by binary 
1’s), the context(s) is searched until an object is encountered with the designated type, subtype, 
and name and for which the process currently has all required authorization states. 


« If the system pointer specified by operand 1 is currently resolved to address an existing object, the 
instruction does not modify the addressability contained in the pointer and causes only the 
authority attribute in the pointer to be modified based on operand 4. 


If operand 2 is not null, the operand 1 system pointer is resolved to the object identified by operand 2 
in the context(s) specified by operand 3. The format of operand 2 is as follows: 


e Object specification Char(32) 
— Type code Char(1) 
— Subtype code Char(1) 
— Object name Char(30) 
e Required authorization (1 = required) Char(2) 
— Object control : ‘ Bit O 
— Object management Bit 1 
— Authorized pointer Bit 2 2 
— Space authority Bit 3 
— Retrieve Bit 4 
— Insert Bit 5 
— Delete Bit 6 
— Update Bit 7 
— Ownership Bit 8 
— Excluded Bit 9 
— Authority List Management Bit 10 
— Reserved (binary 0) Bit 11-15 


The allowed type codes are as follows: 


Hex 01 = Access group 
Hex 02 = Program 

Hex 03 = Module 

Hex 04 = Context 

Hex 06 = Byte string space 
Hex 07 = Journal space 
Hex 08 = User profile 

Hex 09 = Journal port 

Hex OA = Queue 

Hex 0B = Data space 2 
Hex OC = Data space index 
Hex OD = Cursor 

Hex OE = Index 
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Resolve System Pointer (RSLVSP) 


Hex OF = Commit block 

Hex 10 = Logical unit description 

Hex 11 = Network description 

Hex 12 = Controller description 

Hex 13 = Dump space 

Hex 14 = Class of Service Description 
Hex 15 = Mode description 

Hex 16 = Network interface description 
Hex 17 = Connection list 

Hex 18 = Queue space 

Hex 19 = Space 

Hex 1A = Process control space 

Hex 1B = Authorization list 

Hex 1C = Dictionary 


All other codes are reserved. If other codes are specified, they cause a scalar value invalid (hex 3203) 
exception to be signaled. 


Operand 3 identifies the context in which to locate the object identified by operand 2. If operand 3 is 
null, then the contexts identified in the process name resolution list are searched in the order in which 
they appear in the list. If operand 3 is not null, the system pointer specified must address a context, 
and only this context is used to locate the object. If the object is of a type that can only be addressed 
through the machine context, then only the machine context is searched, and operand 3 and the 
process name resolution list are ignored. 


lf the required authorization field in operand 2 is not set (all values set to 0), the instruction resolves 
the operand 1 system pointer to the first object encountered with the designated type code, subtype 
code, and object name without regard to the authorization currently available to the process. If one or 
more authorization (or ownership) states are required (signified by binary 1’s), the context is searched 
until an object is encountered with the designated type code, subtype code, object name, and the user 
profiles governing the instruction’s execution that have all the required authorization states. 


Once addressability has been set in the pointer, operand 4 is used to determine which, if any, of the 
object authority states is to be set into the pointer. Only the object authority states correlating with 
bits 0 through 7, that is, object control through update, can be set into the pointer. This restriction 
applies whether the authority mask controlling which authorities to set in the pointer comes from 
Operand 4, operand 2, or the initial value for the system pointer. 


If operand 4 is null, the object authority states required to locate the object are set in the pointer. This 
required object authority is as specified in operand 2 or in the initial value for operand 1 if operand 2 is 
null. !f the process does not currently have authorized pointer authority for the object, no authority is 
stored in the system pointer, and no exception is signaled. 


If operands 2 and 4 are null and operand 1 is a resolved system pointer, the authority states in the 
pointer are not modified. 


lf operand 4 is not null, it specifies the object authority states to be set in the resolved system pointer. 
The format of operand 4 is as follows: 


e Requested authorization (1 = set authority) Char(2) 
— Object control Bit O 
— Object management Bit 1 
— Authorized pointer Bit 2 
— Space authority Bit 2 
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— Retrieve Bit 4 

— Insert Bit 5 2 
— Delete Bit 6 

— Update Bit 7 

— Reserved (binary 0) Bits 8-15 


The authority states set in the resolved system pointer are based on the following: 


e The authority already stored in the pointer can be increased only when the process has authorized 
pointer authority to the referenced object. If this authority is not available and the pointer was 
resolved by this instruction, the authority in the operand 1 system pointer is set to the not set state, 
and no exception is signaled. If operand 2 is null, if operand 1 is a resolved system pointer con- 
taining authority, and if authorized pointer authority is not available to the process, additional 
authorities cannot be stored in the pointer. 


e If the process does not currently have all the authority states requested in operand 4, only the 
requested and available states are set in the pointer, and no exception is signaled. 


e Note that the authority stored in the operand 1 system pointer is a source of authority applies to 
this instruction when operand 2 is null and operand 1 is a resolved system pointer with authority 
stored in it. 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution (including operand 3) 


Lock Enforcement 
¢ Materialization 


— Contexts referenced for address resolution (including operand 3) 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 Space addressing violation X X X X 
02 Boundary alignment X X X X 
03 Range X X Xx X 
06 Optimized addressability invalid X Xx X X 
08 Argument/parameter 
01 Parameter reference violation X X X X 
0A Authorization 
01 Unauthorized for operation X X 
10 Damage encountered 
02 Machine context damage state X 
04 System object damage state X X X Xx X 
05 authority verification terminated due to damaged object X 
44 Partial system object damage X X X X X 
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Operands 
Exception 1 2 3 4 Other 


1A Lock state 
01 Invalid lock state Xx XxX 


20 Machine support 
02 Machine check xX 
03 Function check Xx 


22 Object access 
01 Object not found X X X X 
02 Object destroyed 
03 Object suspended X X X X 


07 authority verification terminated due to destroyed object X 


*< 
x< 
x< 
x< 


08 object compressed X 


24 Pointer specification 
01 Pointer does not exist X X X X 
02 Pointer type invalid X X X X 


04 Pointer not resolved X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
02 Scalar attributes invalid X X 


03 Scalar value invalid Xx D4 


36 Space management 


01 space extension/truncation X 
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Set Space Pointer from Pointer (SETSPPFP) 


Op Code (Hex) Operand 1 Operand 2 
0022 Receiver Source Pointer 


Operand 1: Space pointer. 
Operand 2: Data pointer, system pointer, or space pointer. 


Description: A space pointer is returned in operand 1 with the addressability to a space object from 
the pointer specified by operand 2. 


The meaning of the pointers allowed for operand 2 is as follows: 


Pointer Meaning 

Data pointer or The space pointer returned in operand 1 is set to address of the leftmost byte of the byte 
space pointer string addressed by the source pointer for operand 2. 

System pointer The space pointer returned in operand 1 is set to address the first byte of the space con- 


tained in the system object addressed by the system pointer for operand 2. The space 
object addressed is either the created system space or an associated space for the system 
object addressed by the system pointer. If the operand 2 system pointer addresses a 
system object with no associated space, the invalid space reference (hex 0605) exception 
is signaled. 


The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, 
parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are 


not signaled when operand 1 and operand 2 are space pointer machine objects. This occurs when é ' 


operand 2 contains an internal machine value that indicates one of these error conditions exists. If the 
corresponding exception is not signaled, operand 1 is set with an internal machine value that pre- 
serves the exception condition that existed for operand 2. The appropriate exception condition will be 
signaled for either pointer when a subsequent attempt is made to reference the space data that the 
pointer addresses. 


Authorization Required 
e Space authority 
— Operand 2 (if a system pointer) 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation X X 
02 boundary alignment X X 
03 range X X 
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Exception 


08 


0A 


10 


1A 


20 


22 


24 


2E 


36 


04 external data object not found 
05 invalid space reference 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Operands 
1 2 
X 
X 
X X 
X 
X X 
X X 
X 
X X 
X X 
X X 
X X 
X X 
X 


Other 


x 
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Set System Pointer from Pointer (SETSPFP) 


Op Code (Hex) Operand 1 Operand 2 
0032 Receiver Source pointer 


Operand ?: System pointer. 
Operand 2: System pointer, space pointer, data pointer, or instruction pointer. 


Description: This instruction returns a system pointer to the system object address by the supplied 
pointer. 


If operand 2 is a system pointer, then a system pointer addressing the same object is returned in 
operand 1 containing the same authority as the input pointer. 


lf operand 2 is a space pointer or a data pointer, then a system pointer addressing the system object 
that contains the associated space addressed by operand 2 is returned in operand 1. 


If operand 2 is an instruction pointer, then a system pointer addressing the program system object that 
contains the instruction addressed by operand 2 is returned in operand 1. 


lf operand 2 is an unresolved system pointer or data pointer, the pointer is resolved first. 


Authorization Required . 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialization 


— Contexts referenced for address resolution 


Exceptions 

Operands 
Exception 1 2 Other 
06 Addressing 


01 space addressing violation 
02 boundary alignment 
03 range 


04 external data object not found 


x KKK OX 
x KX KK MK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 
02 machine context damage X 


04 system object damage state X X X 
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Bits, 


Exception 
05 authority verification terminated due to damaged object X 


1A 


20 


22 


24 


2E 


32 


36 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


Set System Pointer from Pointer (SETSPFP) 


Operands 
1 2 Other 


X X x 


07 authority verification terminated due to destroyed object X 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 
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space Addressing Instructions 


Chapter 5. Space Addressing Instructions J 


This chapter describes the instructions used for space addressing. These instructions are in alpha- 
betic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary” 


Add Space Pointer (ADDSPP) ....... 2... 0... 2 ee ee eee 5-3 
Compare Space Addressability (CMPSPAD) ............0.0. 00.0000 0 2 eee eee eee 5-5 
oer Data. PoIntier(SElTOP): 22-6 ou feck eee AOE RES BEARERS ES ER EE we ee Se 5-7 
Set Data Pointer Addressability (SETDPADR) ..............0. 0.0.00 2 eee ee eee eee 5-9 
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Add Space Pointer (ADDSPP) 


Add Space Pointer (ADDSPP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0083 Receiver Pointer Source Pointer Increment 


Operand f: Space pointer. 
Operand 2: Space pointer. 
Operand 3: Binary scalar. 


Description: This instruction adds a signed or unsigned binary value to the offset of a space pointer. 
The value of the binary scalar represented by operand 3 is added to the space address contained in 
the space pointer specified by operand 2, and the result is stored in the space pointer identified by 
operand 1. l.e. 


Operand 1 = Operand 2 + Operand 3 


Operand 3 can have a positive or negative value. The space object that the pointer is addressing is 
not changed by the instruction. 


Operand 2 must contain a space pointer when the execution of the instruction is initiated; otherwise, 
an invalid pointer type (hex 2402) exception is signaled. When the addressability in a space pointer is 
modified, the instruction signals a space addressing (hex 0601) exception only when the space address 
to be stored in the pointer has a negative offset value or when the offset addresses beyond the largest 
space allocatable in the object. This maximum offset value is dependent on the size and packaging of 
the object containing the space and is independent of the actual size of the space allocated. If the 
exception is signaled by this instruction for this reason, the pointer is not modified by the instruction. 
Attempts to use a pointer whose offset value lies between the currently allocated extent of the space 
and the maximum allocatable extent of the space cause the space addressing (hex 0601) exception to 
be signaled. 


The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, 
parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are 
not signaled when operand 1 and operand 2 are space pointer machine objects. This occurs when 
operand 2 contains an internal machine value that indicates one of these error conditions exists. If the 
corresponding exception is not signaled, operand 1 is set with an internal machine value that pre- 
serves the exception condition that existed for operand 2. The appropriate exception condition will be 
signaled for either pointer when a subsequent attempt is made to reference the space data that the 
pointer addresses. 


Exceptions 


Exception 1 2 3[4-6] Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KX K KK 
x KK XK 
x KX K XK 


06 optimized addressability invalid 


08 Argument/parameter 
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J 


Exception 


10 


1c 


20 


22 


24 


2E 


36 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 abject compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Add Space Pointer (ADDSPP) 


Operands 
1 2 34-6] Other 
X X X 
X X X X 
X X X X 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
Xx xX xX 
X 
X 
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Compare Space Addressability (CMPSPAD) 


Compare Space Addressability (CMPSPAD) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 [4-6] > 
CMPSPADB Branch options Compare Compare Branch targets 

1CF2 operand 1 operand 2 

CMPSPADI Indicator options Compare Compare Indicator targets 

18F2 operand 1 operand 2 


Operand 1: Numeric variable scalar, character variable scalar, numeric variable array, character vari- 
able array, pointer data object, pointer data object array. 


Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character vari- 
able array, pointer data object, pointer data object array. 


Operand 3 [4-6]: 
e Branch Form-|nstruction number, relative instruction number, branch point, or instruction pointer. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The space addressability of the object specified by operand 1 is compared with the space 
addressability of the object specified by operand 2. 


Based on the results of the comparison, the resulting condition is used with the extender to transfer 

control (branch form) or to assign a value to each of the indicator operands (indicator form). If the 

operands are not in the same space, the resultant condition is unequal. If the operands are in the 

Same space and the offset of operand 1 is larger or smaller than the offset of operand 2, the resultant a 
condition is high or low, respectively. Equal occurs only if the operands are in the same space at the ad 
same offset. Therefore, the resultant conditions (high, low, equal, and unequal) are mutually exclusive. 
Consequently, if you specify that an action be taken upon the nonexistence of a condition, this results 

in the action being taken upon the occurrence of any of the other three possible conditions. For 

example, a branch not high would result in the branch being taken on a /ow, equal, or unequal condi- 

tion. 


If a pointer data object operand contains a data pointer value upon execution of the instruction, the 
addressability is compared to the pointer data object rather than to the scalar described by the data 
pointer value. The variable scalar references allowed on operands 1 and 2 cannot be described 
through a data pointer value. 


The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, 
parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are 
not signaled when operand 1 or operand 2 is based on a space pointer machine object. This occurs 
when the space pointer machine object contains an internal machine value that indicates one of these 
error conditions exists. If the corresponding exception is not signaled, the resulting condition of the 
comparison operation is not defined other than that it will be one of the four valid resultant conditions 
for this instruction. 


Resultant Conditions 
¢ High 


e Low 


e Equal 2 


e Unequal 
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Compare Space Addressability (CMPSPAD) 


Exceptions 
Operands 
Exception 1 2 3 [4-6] Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK XK 
x K KK 
x KX KK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


10 Damage encountered 
04 system object damage state X X X X 
44 partial system object damage X X X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check . Xx 


22 Object access 
01 object not found X X X 
02 object destroyed 
03 object suspended X X X 


08 object compressed X 


x< 
x< 
x< 


24 Pointer specification 
01 pointer does not exist X X X 


02 pointer type invalid X X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X 


Chapter 5. Space Addressing Instructions 5-6 


Set Data Pointer (SETDP) 


Set Data Pointer (SETDP) 


Op Code (Hex) Operand 1 Operand 2 
0096 Receiver Source 


Operand ?f: Data pointer. 


Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, or character 
variable array. 


Description: A data pointer is created and returned in the storage area specified by operand 1 and 
has the attributes and space addressability of the object specified by operand 2. Addressability is set 
to the low-order (leftmost) byte of the object specified by operand 2. The attributes given to the data 
pointer include scalar type and scalar length. 


If operand 2 is a substring compound operand, the length attribute is set equal to the length of the 
substring. If operand 2 is a subscript compound operand, the attributes and addressability of the 
single array element specified are assigned to the data pointer. If operand 2 is an array, the attributes 
and addressability of the first element of the array are assigned to the data pointer. A data pointer can 
only be set to describe an element of a data array, not a data array in its entirety. 


When the addressability in the data pointer is modified, the instruction signals the space addressing 
(hex 0601) exception when one of the following conditions occurs: 


e When the space address to be stored in the pointer would have a negative offset value. 


e When the offset would address an area beyond the largest space allocatable in the object. This 
maximum offset value is dependent on the size and packaging of the object containing the space 
and is independent of the actual size of the space allocated. 


If the exception is signaled by this instruction for one of these reasons, the pointer is not modified by 
the instruction. 


Attempts to use a pointer whose offset value lies between the currently allocated extent of the space 
and the maximum allocatable extent cause the space addressing (hex 0601) exception to be signaled. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation Xx X 
10 Damage encountered 

04 system object damage state X X X 

44 partial system object damage X X X 
1C Machine-dependent exception 

03 machine storage limit exceeded X 
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Exception 


20 


22 


24 


2E 


36 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Set Data Pointer (SETDP) 


Operands 
1 2 Other 


X 
XK 
X 
X X 
X X 
X 
X X 
X X 
X 
X 
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Set Data Pointer Addressability (SETDPADR) 


Set Data Pointer Addressability (SETDPADR) 


Op Code (Hex) Operand 1 Operand 2 - 
0046 Receiver Source 


Operand 1: Data pointer. 


Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, or character 
variable array. 


Description: The space addressability of the object specified for operand 2 is assigned to the data 
pointer specified by operand 1. If operand 1 contains a resolved data pointer, the data pointer’s scalar 
attribute component is not changed by the instruction. If operand 1 contains an initialized but unre- 
solved data pointer, the data pointer is resolved in order to establish the scalar attribute component of 
the pointer. If operand 1 contains other than a resolved data pointer, the instruction creates and 
returns a data pointer in operand 1 with the addressability of the object specified for operand 2, and 
the instruction establishes the attributes as a character(1) scalar. 


When the addressability is set into a data pointer, the space addressing (hex 0601) exception is sig- 
naled by the instruction only when the space address to be stored in the pointer has a negative offset 
value or if the offset addresses beyond the largest space allocatable in the object. This maximum 
offset value is dependent on the size and packaging of the object containing the space and is inde- 
pendent of the actual size of the space allocated. If the exception is signaled for this reason, the 
pointer is not modified by the instruction. Attempts to use a pointer whose offset value lies between 
the currently allocated extent of the space and the maximum allocatable extent of the space cause the 
Space addressing (hex 0601) exception to be signaled. 


} 
J 
Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

04 external data object not found X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation Xx X 
10 Damage encountered 

04 system object damage state X Xx X 

44 partial system object damage X X X 
1C Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check x 

03 function check X >) 


22 Object access 
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Set Data Pointer Addressability (SETDPADR) 


Operands 
Exception 1 2 Other 
01 object not found 


X X 
02 object destroyed X X 
03 object suspended X X 


08 object compressed X 


24 Pointer specification 
01 pointer does nat exist X X 


02 pointer type invalid X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X 
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Set Data Pointer Attributes (SETDPAT) 


Op Code (Hex) 
004A 


Operand 1 Operand 2 
Receiver Attributes 


Operand 1: Data pointer. 


Operand 2: Character(7) scalar. 


Set Data Pointer Attributes (SETDPAT) 


Description: The value of the character scalar specified by operand 2 is interpreted as an encoded 
representation of an attribute set that is assigned to the attribute portion of the data pointer specified 
by operand 1. The addressability portion of the data pointer is not modified. If operand 1 contains an 
initialized but unresolved data pointer, the data pointer is resolved in order to establish the address- 
ability in the pointer. The attributes specified by the instruction are then assigned to the data pointer. 
If operand 1 does not contain a data pointer at the initiation of the instruction’s execution, an exception 


is signaled. 


The format of the attribute set is as follows: 


e Data pointer attributes 


— Scalar type 
Hex 00 = Signed binary 
Hex 01 = Floating-point 
Hex 02 = Zoned decimal 
Hex 03 = Packed decimal 
Hex 04 = Character 
Hex 06 = Onlyns 
Hex 07 = Onlys 
Hex 08 = Either 
Hex 09 = Open 
Hex 0A = Unsigned binary 


— Scalar length 


lf binary or character: 


Length (only 2 or 4 for binary) 


If floating-point: 


Length (only 4 or 8 for floating-point) 


If zoned decimal or packed decimal: 


Fractional digits (F) 


Total digits (T) 
(where 1 <7 <31,0<SF ST) 


If character: 


Length (L, where 1 < L $ 32767) 


If Onlyns: 


Length (L, where 1 < L < 16,383) 


L is the number of double-byte characters. 


If Onlys: 


Length (L, where 2 < L < 32,766) 


Char(7) 
Char(‘1) 


Bin(2) 


Bits 0-7 
Bits 8-15 
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| em 
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e Lis the number of bytes 


* Lis even 


e L includes any SO and SI characters 


lf Either: 


- Length (L, where 1 <L < 32,766) 


e Lis the number of bytes 
e Lincludes any SO and SI characters. 


If Open: 


- Length (L, where 2 <L < 32,766) 


e Lis the number of bytes 
e Lincludes any SO and SI characters. 


Reserved (binary 0) 


Set Data Pointer Attributes (SETDPAT) 


Bin(4) 


Support for usage of a Data Pointer describing an Onlyns, Onlys, Either, or Open scalar value is limited 
to the Copy Extended Characters Left Adjusted With Pad instruction. Usage of such a data pointer 
defined value on any other instruction is not supported and results in the signaling of the sca/ar type 
invalid (hex 3201) exception. 


Exceptions 


Exception 


06 


08 


1C 


20 


22 


24 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

04 external data object not found 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 


08 object compressed 


Pointer specification 


X X 

X X 

X X 

X 

X X 

X X 

X X X 

X X X 
X 
X 
X 

X X 

X X 

X X 
X 
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Exception 
01 pointer does not exist 


02 pointer type invalid 


2E Resource control limit 


01 user profile storage limit exceeded 


32 Scalar specifications 
01 scalar type invalid 
02 scalar attributes invalid 


03 scalar value invalid 


36 Space management 


01 space extension/truncation 


set Data Pointer Attributes (SETDPAT) 


Operands 
1 2 Other 
X X 
Xx X 
X 
X 
X 
X 
X 
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Set Space Pointer (SETSPP) 


Set Space Pointer (SETSPP) 


Op Code (Hex) Operand 1 Operand 2 
0082 Receiver Source 


Operand 7: Space pointer. 


Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character vari- 
able array, or pointer data object. 


Description: A space pointer is returned in operand 1 and is set to address the lowest order (leftmost) 
byte of the byte string identified by operand 2. 


When the addressability is set in a space pointer, the instruction signals the space addressing (hex 
0601) exception when the offset addresses beyond the largest space allocatable in the object or when 
the space address to be stored in the pointer has a nonpositive offset value. This. offset value is 
dependent on the size and packaging of the object containing the space and is independent of the 
actual size of the space allocated. If the exception is signaled for this reason, the pointer is not modi- 
fied by the instruction. Attempts to use a pointer whose offset value lies between the currently allo- 
cated extent of the space and the maximum allocatable extent of the space cause the space addressing 
(hex 0601) exception to be signaled. 


If a pointer data object specified for operand 2 contains a data pointer value upon execution of the 
instruction, the addressability is set to the pointer storage form rather than to the scalar described by 
the data pointer value. The variable scalar references allowed on operand 2 cannot be described 
through a data pointer value. 


The object destroyed (hex 2202) exception, the optimized addressability invalid (nex 0606) exception, 
the parameter reference violation (hex 0801) exception, and the pointer does not exist (hex 2401) excep- 
tion are not signaled when operand 1 is a space pointer machine object and operand 2 is based on a 
space pointer machine object. This occurs when the basing space pointer machine object for operand 
2 contains an internal machine value that indicates one of these error conditions exists. If the corre- 
sponding exception is not signaled, operand 1 is set with an internal machine value that preserves the 
exception condition which existed for operand 2. The appropriate exception condition is signaled for 
either pointer upon a subsequent attempt to reference the space data the pointer addresses. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
10 Damage encountered 

04 system object damage state X xX X 

44 partial system object damage X X xX 
1C Machine-dependent exception 
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Exception 


20 


22 


24 


2E 


32 


36 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 abject suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Set Space Pointer (SETSPP) 


Operands 
1 2 Other 
X 
X 
X 
X 
X X 
X X 
X 
X X 
X X 
X 
X X 
X 
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Set Space Pointer with Displacement (SETSPPD) 


Set Space Pointer with Displacement (SETSPPD) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0093 Receiver Source Displacement 


Operand 1: Space pointer. 


Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character vari- 
able array, or pointer data object. 


Operand 3: Binary scalar. 


Description: A space pointer is returned in operand 1 and is set to the space addressability of the 
lowest (leftmost) byte of the object specified for operand 2 as modified algebraically by an integer dis- 
placement specified by operand 3. Operand 3 can have a positive or negative value. l.e. 


Operand 1 = Address of(Operand 2) + Operand 3 


When the addressability is set in a space pointer, the instruction signals the space addressing (hex 
0601) exception when the space address to be stored in the pointer has a negative offset value or 
when the offset addresses beyond the largest space allocatable in the object. This maximum offset 
value is dependent on the size and packaging of the object containing the space and is independent of 
the actual size of the space allocated. If the exception is signaled for this reason, the pointer is not 
modified by the instruction. Attempts to use a pointer whose offset value lies between the currently 
allocated extent of the space and the maximum allocatable extent of the space cause the space 
addressing (hex 0601) exception to be signaled. 


If a pointer data object specified for operand 2 contains a data pointer value upon execution of the 
instruction, the addressability is set to the pointer storage form rather than to the scalar described by 
the data pointer value. The variable scalar references allowed on operand 2 cannot be described 
through a data pointer value. 


The object destroyed (hex 2202) exception, the optimized addressability invalid (hex 0606) exception, 
the parameter reference violation (hex 0801) exception, and the pointer does not exist (hex 2401) excep- 
tion are not signaled when operand 1 is a space pointer machine object and operand 2 is based on a 
space pointer machine object. This occurs when the basing space pointer machine object for operand 
2 contains an internal machine value that indicates one of these error conditions exists. If the corre- 
sponding exception is not signaled, operand 1 is set with an internal machine value that preserves the 
exception condition which existed for operand 2. The appropriate exception condition is signaled for 
either pointer upon a subsequent attempt is made to reference the space data the pointer addresses. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation xX X xX 

02 boundary alignment xX X xX 

03 range X Xx X 

06 optimized addressability invalid Xx Xx Xx 


08 Argument/parameter 
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Set Space Pointer with Displacement (SETSPPD) 


Operands 

Exception 1 2 Other 

01 parameter reference violation X X X 
10 Damage encountered 

04 system object damage state X X X X 

44 partial system object damage X X X X 
1c Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check X 

03 function check X 
22 Object access 

01 object not found X X X 

02 object destroyed X X X 

03 object suspended X X xX 

08 object compressed X 
24 Pointer specification 

01 pointer does not exist X X X 

02 pointer type invalid x X X 
2E Resource control limit ; 

01 user profile storage limit exceeded X J 
36 Space management 

01 space extension/truncation X 
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Set Space Pointer Offset (SETSPPO) 


Set Space Pointer Offset (SETSPPO) 


Op Cade (Hex) Operand 1 Operand 2 
0092 Receiver Source 1 


Operand 1: Space pointer. 
Operand 2: Binary scalar. 


Description: The value of the binary scalar specified by operand 2 is assigned to the offset portion of 
the space pointer identified by operand 1. The space pointer continues to address the same space 
object. 


Operand 1 must contain a space pointer; otherwise, an invalid pointer type (hex 2402) exception is sig- 
naled. 


When the addressability in the space pointer is modified, the instruction signals a space addressing 
(hex 0601) exception when one of the following conditions occurs: 
e The space address to be stored in the pointer has a negative offset value. 


e The offset addresses beyond the largest space allocatable in the object. This maximum offset 
value is dependent on the size and packaging of the object containing the space and is inde- 
pendent of the actual size of the space allocated. 


If the exception is signaled by this instruction for this reason, the pointer is not modified by the instruc- 
tion. 


Attempts to use a pointer whose offset value lies between the currently allocated extent of the space 
and the maximum allocatable extent cause the space addressing (hex 0601) exception to be signaled. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation xX Xx 
10 Damage encountered 

04 system object damage state » 4 »¢ xX 

44 partial system object damage X X X 
1C Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check X 

03 function check X 
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Exception 


22 


24 


2E 


32 


36 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


set Space Pointer Offset (SETSPPO) 


Operands 
1 2 Other 


~2 


X X 
X X 
X X 

X 
X X 
X X 

X 
X X 

X 
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Store Space Pointer Offset (STSPPO) 


Op Code (Hex) Operand 1 


00A2 


Receiver 


Operand 7: Binary variable scalar. 


Operand 2: Space pointer. 


Store Space Pointer Offset (STSPPO) 


Description: The offset value of the space pointer referenced by operand 2 is stored in the binary 
variable scalar defined by operand 1. 


If operand 2 does not contain a space pointer at the initiation of the instruction’s execution, an invalid 


pointer type (nex 2401) exception is signaled. 


If binary size (hex OCOA) exceptions are to be signaled either because the program creation attribute 
indicated to do so or because a translator directive indicated to do so, they will be signalled under the 
following conditions. If the offset value is greater than 32 767 and operand 1 is a signed binary (2) 
scalar, a size (hex OCOA) exception is signaled. If the offset value is greater than 65 535 and operand 1 
is an unsigned binary (2) scalar, a size (hex OCOA) exception is signaled. 


Exceptions 


Exception 


06 


08 


0c 


10 


1c 


20 


22 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Computations 


0A size 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


Operands 
1 2 Other 


X X 

X X 

X X 

X X 

X X 

X 

X X X 

X X X 
X 
X 
X 

X X 

X X 

X x 
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Store Space Pointer Offset (STSPPO) 


Operands 
Exception 1 2 Other 
08 object compressed xX 
24 Pointer specification 
01 pointer does not exist X X 


02 pointer type invalid 4 x 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X 
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Subtract Space Pointer Offset (SUBSPP) 


Subtract Space Pointer Offset (SUBSPP) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0087 Receiver pointer Source pointer Decrement 


Operand 7: Space pointer. 
Operand 2: Space pointer. 
Operand 3: Binary scalar. 


Description: The value of the binary scalar specified by operand 3 is subtracted from the space 
address contained in the space pointer specified by operand 2; the result is stored in the space pointer 
identified by operand 1. l.e. 


OQperand 1 = Operand 2 - Operand 3 


Operand 3 can have a positive or negative value. The space object that the pointer is addressing is 
not changed by the instruction. If operand 2 does not contain a space pointer at the initiation of the 
instruction’s execution, an invalid pointer type (hex 2402) exception is signaled. 


When the addressability in the space pointer is modified, the instruction signals a space addressing 
(hex 0601) exception when one of the following conditions occurs: 


e The space address to be stored in the pointer has a negative offset value. 


¢« The offset addresses beyond the largest space allocatable in the object. This maximum offset 
value is dependent on the size and packaging of the object containing the space and is inde- 
pendent of the actual size of the space allocated. 


If the exception is signaled by this instruction for this reason, the pointer is not modified by the instruc- 
tion. 


Attempts to use a pointer whose offset value lies between the currently allocated extent of the space 
and the maximum allocatable extent cause the space addressing exception to be signaled. 


The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, 
parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are 
not signaled when operand 1 and operand 2 are space pointer machine objects. This occurs when 
operand 2 contains an internal machine value that indicates one of these error conditions exists. If the 
corresponding exception is not signaled, operand 1 is set with an internal machine value that pre- 
serves the exception condition that existed for operand 2. The appropriate exception condition will be 
signaled for either pointer when a subsequent attempt is made to reference the space data that the 
pointer addresses. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x «x x x 
x x * xX 
x x x x 


06 optimized addressability invalid 
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Exception 


08 


10 


20 


22 


24 


2E 


36 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Subtract Space Pointer Offset (SUBSPP) 


Operands 

1 2 3 Other 

X X X 

X X X X 

X X X X 
X 
X 
X 

X X Xx 

X X X 

X X X 
X 

Xx xX xX 

X X X 

X X X 

X X X 
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Subtract Space Pointers For Offset (SUBSPPFQO) 


Subtract Space Pointers For Offset (SUBSPPFO) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0033 Offset Difference Minuend pointer Subtrahend 
pointer 


Operand ?: Binary(4) variable scalar. 
Operand 2: Space pointer. 
Operand 3: Space pointer. 


Description: The offset portion of the space address contained in the operand 3 space pointer is sub- 
tracted from the offset of the space address contained in the space pointer specified by operand 2; the 
result is stored in the 4 byte binary scalar identified by operand 1. |.e. 


Operand 1 = Address of(Qperand 2) - Address of(Operand 3) 


The offsets for operands 2 and 3 are strictly unsigned values, while the operand 1 result can have a 
positive or negative value. 


No check is made to determine that the space pointers point to the same space. In addition, the exist- 
ence of the pointers is not checked except for pointers used as a base for the operands. When the 
space pointers point to different spaces, or one or both of the pointer operands is subject to the pointer 
does not exist condition, the resulting value is undefined, but no exception is signaled. However, if 
both operand 2 and operand 3 are subject to the pointer does not exist condition, the result value is 
zero. 


lf either operand 2 or operand 3 contains a pointer which is not a space pointer at the initiation of the 
instruction’s execution, an invalid pointer type (hex 2402) exception is signaled. 


A size (nex OQCOA) exception occurs when the operand 1 field is unsigned binary, the resulting value of 
the subtraction is negative, and the program attribute to signal size exceptions is in effect. 


The object destroyed (hex 2202) exception, optimized addressability invalid (nex 0606) exception, 
parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are 
not signaled when operand 2 and operand 3 are space pointer machine objects. This occurs when 
operand 2 or operand 3 contains an internal machine value that indicates one of these error conditions 
exists. If the corresponding exception is not signaled, operand 1 is undefined, but no exception is sig- 
naled. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X X 
03 range X X X 
06 optimized addressability invalid X X X 
08 Argument/parameter 
01 parameter reference violation X X X 
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Operands 
Exception 1 2 3 Other 
10 Damage encountered > 
04 system object damage state X X X X 
44 partial system object damage X X X X 
0c Computation 
0A Size X 
1c Machine-dependent exception 
03 machine storage limit exceeded X 
20 Machine support 
02 machine check X 
03 function check X 
22 Object access 
01 object not found Xx X X 
02 object destroyed X X X 
03 object suspended X X X 
08 object compressed X 
24 Pointer specification 
01 pointer does not exist X X X 
02 pointer type invalid X X X 
2E Resource control limit o 
01 user profile storage limit exceeded X X X 
36 Space management 
01 space extension/truncation Xx X X 
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Chapter 6. Space Management Instructions 


This chapter describes the instructions used for space management. These instructions are in alpha- 
betic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 
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Materialize Space Attributes (MATS) ........0.. 2.0.0.0 0 0. ee es 6-11 
Modify Space Attributes (MODS) ..........0.0.0.0. 0.0.00 ee ee 6-15 
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Create Space (CRTS) 


Op Code (Hex) Operand 1 Operand 2 
0072 Pointer for space Space creation 
addressability template 


Operand ?f: System pointer. 


Operand 2: Space pointer. 


ILE access 


CRTS ( 
var space obj : system pointer; 
creation template : space pointer 


Create Space (CRTS) 


Description: A space object is created with the attributes that are specified in the space creation tem- 
plate specified by operand 2, and addressability to the created space is placed in a system pointer that 


is returned in the addressing object specified by operand 1. 


Space objects, unlike other types of system objects, are used to contain a space and serve no other 


purposes. 


The template identified by operand 2 must be 16-byte aligned in the space. The following is the format 


of the space creation template: 
e Template size specification 
— Size of template 
— Number of bytes available for materialization 
e« Object identification 
— Object type 
— Object subtype 
— Object name 
« Object creation options 
— Existence attribute 


0 = Temporary 
1 = Permanent 


— Space attribute 


0 = Fixed-length 
1 = Variable-length 


— Initial context 


O = Addressability is not inserted into context 
1 = Addressability is inserted into context 


— Access group 


0 
4 


— Reserved (binary 0) 


Do not create as member of access group 
Create as member of access group 


Char(8)* 
Bin(4)* 
Bin(4)* 
Char(32) 
Char(1)* 
Char(1) 
Char(30) 
Char(4) 
Bit O 


Bit 1 


Bit 2 


Bit 3 


Bits 4-5 
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— Public authority specified Bit 6 
Q = No 
1 = Yes 2 
— Initial owner specified Bit 7 
QO = No 
1 = Yes 
— Reserved (binary 0) Bits 8-11 
— Set public authority in operand 1 Bit 12 
Q = No 
1 = Yes 
— Initialize space Bit 13 
0 = Initialize 
1 = Do not initialize 
— Automatically extend space Bit 14 
0 = No 
1 = Yes 
— Hardware storage protection level Bits 15-16 
00 = Reference and modify allowed for user state programs 
01 = Only reference allowed for user state programs 
10 = Invalid (yields template value invalid (hex 3801) exception) 
11 = No reference or modify allowed for user state programs i 
— Process temporary space accounting Bit 17 2 
= The temporary space will be tracked to the creating process 
1 = The temporary space will not be tracked to the creating process 
— Reserved (binary 0) Bits 18-31 
Recovery options Char(4) 
— Reserved (binary 0) Char(2) 
— ASP number Char(2) 
Size of space Bin(4) 
Initial value of space Char(1) 
Performance class Char(4) 
— Space alignment Bit O 
0 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, this value must 
be specified for the performance class. 
1 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space as well as to allow proper alignment of input/output 
buffers at 512-byte alignments within the space. 
— Clear the space into main memory Bit 1 
during creation 
0 = Only a minimum amount (up to 4K) of the space will be in main storage upon completion | 
of the instruction. = | 


1 = Most of the space, with some limits enforced by the machine, will be in main storage upon 
completion of the instruction. 
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— Reserved (binary 0) Bits 2-4 
— Main storage pool selection Bit 5 


0 Process default main storage pool is used for object. 
1 = Machine default main storage pool is used for object. 


— Transient storage pool selection Bit 6 


O = Default main storage pool (process default or machine default as specified for main 
storage pool selection) is used for object. 
1 = Transient storage pool is used for object. 


— Block transfer on implicit access Bit 7 
state modification 


= Transfer the minimum storage transfer size for this object. This value is 1 storage unit. 
1 = Transfer the machine default storage transfer size. This value is 8 storage units. 


— Unit number Bits 8-15 
— Reserved (binary 0) Bits 16-31 
e Reserved (binary 0) Char(1) 
e Public authority Char(2) 
¢ Extension offset Bin(4) 
¢« Context System pointer 
e Access group - System pointer 


Note: The instruction ignores the values associated with template entries annotated with an asterisk 
(*). 
A template extension must be specified for the initial owner specified creation option. Also, the tem- 


plate extension must be specified (extension offset must be nonzero) to specify any of the other tem- 
plate extension fields (those other than the initial owner user profile) as input to the instruction. 


The template extension is located by the extension offset field. The template extension must be 
16-byte aligned in the space. The following is the format of the template extension: 


e User profile System pointer 
e Largest size needed for space Bin(4) 
¢ Domain assigned to the object Char(2) 


Hex 0000 The domain will be chosen by the machine. 
Hex 0001 The domain will be ‘Common User’. 
Hex 8000 The domain will be ‘Common System’. 
e Reserved (binary 0) Char(42) 


If the created object is permanent, it is owned by the user profile governing process execution. The 
owning user profile is implicitly assigned all private authority states for the object. The storage occu- 
pied by the created object is charged to this owning user profile. if the created object is temporary, 
there is no owning user profile, and all authority states are assigned as public. Storage occupied by 
the created context is charged to the creating process. 


The object identification specifies the symbolic name that identifies the space within the machine. An 
object type of hex 19 is implicitly supplied by the machine. The object identification is used to identify 
the object on materialize instructions as well as to locate the object in a context that addresses the 
object. The object subtype must be hex EF. 
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The existence attribute specifies whether the space is to be created as temporary or permanent. A 
temporary space, if not explicitly destroyed by the user, is implicitly destroyed by the machine when 
machine processing is terminated. A permanent space exists in the machine until it is explicitly 
destroyed by the user. 


The space attribute specifies whether the size of the space can vary. The space may have a fixed size 
or a variable size. The initial allocation is as specified in the size of space field. The machine allo- 
cates a space of at least the size specified. The actual size allocated depends on an algorithm defined 
by a specific implementation. A fixed size space of zero length causes no space to be allocated. 


If the initial context creation attribute field indicates that addressability is to be inserted into a context, 
the context field must contain a system pointer that identifies a context where addressability to the 
newly created space is to be placed. If addressability is not to be inserted into a context, the context 
field is ignored. 


If the access group creation attribute field indicates that the space is to be created in an access group, 
the access group field must be a system pointer that identifies the access group in which the space is 
to be created. If the space is being created as a member of an access group, the existence attribute 
field must be temporary (bit 0 equals 0). If the space is not to be created into an access group, the 
access group field is ignored. 


The public authority specified creation option controls whether or not the space is to be created with 
the public authority specified in the template. When yes is specified, the space is created with the 
public authority specified in the public authority field of the template. When no is specified, the public 
authority field is ignored and the space is created with default public authority. The default public 
authority depends on the value of the existence attribute: An existence attribute value of temporary 
results in a default public authority of all authority; an existence attribute value of permanent results in 
a default public authority of no authority. Refer to the Grant Authority instruction for a description of 
the public authority field and a list of allowable values. 


The initial owner specified creation option controls whether or not the initial owner of the space is to 
be the user profile specified in the template. When yes is specified, initial ownership is assigned to the 
user profile specified in the user profile field of the template extension. When no is specified, initial 
ownership is assigned to the process user profile and the user profile field in the template extension is 
ignored. The initial owner user profile is implicitly assigned all authority states for the object. The 
storage occupied by the created space is charged to the initial owner. If yes is specified for this cre- 
ation option when the existence attribute specifies temporary, a template value invalid (hex 3801) 
exception will be signaled. 


The set public authority in operand 1 creation option controls, when the public authority specified cre- 
ation option has also been specified as yes, whether or not the public authority attribute for the space 
is to be set into the system pointer returned in operand 1. When yes is specified, the specified public 
authority is set into operand 1. When no is specified, public authority is not set into operand 1. When 
the public authority specified creation option is set to no, this option can not be specified as yes (or 
else a template value invalid (hex 3801) exception will be signalled) and the authority set into operand 
1 is the default of no authority for a permanent or all authority for a temporary object (as specified by 
the existence attribute). 


The initialize space creation option controls whether or not the space is to be initialized. When ini- 
tialize is specified, each byte of the space is initialized to a value specified by the initial value of space 
field. Additionally, when the space is extended in size, this byte value is also used to initialize the new 
allocation. When do not initialize is specified, the initial value of space field is ignored and the initial 
value of the bytes of the space are unpredictable. 


When do not initialize is specified for a space, internal machine algorithms do ensure that any storage 
resources last used for allocations to another object which are reused to satisfy allocations for the 
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space are reset to a machine default value to avoid possible access of data which may have been 
stored in the other object. To the contrary, reusage of storage areas previously used by the space 
object are not reset, thereby exposing subsequent reallocations of those storage areas within the 
space to access of the data which was previously stored within them. 


The automatically extend space creation option controls whether the space is to be extended automat- 
ically by the machine or a space addressing (hex 0601) exception is to be signaled when a reference is 
made to an area beyond the allocated portion of the space. When yes is specified, the space will 
automatically be extended by an amount determined through internal machine algorithms. When no is 
specified, the exception will result. Note that an attempt to reference an area beyond that for the 
maximum size that a space can be allocated, will always result in the signaling of the space addressing 
(hex 0601) exception independently of the setting of this attribute. The automatically extend space cre- 
ation option can only be specified when the space attribute has been specified as variable length. 
Invalid specification of the automatically extend space option results in the signaling of the template 
value invalid (hex 3801) exception. 


Usage of the automatically extend space function is limited. Predictable results will occur only when 
you ensure that the automatic extension of a space will not happen in conjunction with modification of 
the space size by another process. That is, you must ensure that when a process is using the space in 
a manner that could cause it to be automatically extended, it is the sole process which can cause the 
space size to be modified. Note that in addition to implicit modification through automatic extension, 
the space size can be explicitly modified through use of the Modify Space Attributes instruction. 


The hardware storage protection level can be used to restrict access to the contents of the space by 
user state programs. It is possible to limit the access of the space by user state programs into 1 of 
three levels: 


e Reference only (non-modifying storage references are allowed, modifying storing storage refer- 
ences yield a domain/protection violation (hex 4401) exception). 


¢ No storage references (all storage references, modifying or non-modifying yield a 
domain/protection violation (hex 4401) exception). 


e Full access (both modifying and non-modifying storage references are allowed). 


Process temporary space accounting can be used to detect when temporary space objects, created 
within a process, still exist at process termination time. Temporary spaces that are created with the 
process temporary space accounting field set to 0 will be “tracked” to the process which created them. 
Temporary spaces that are created with the process temporary space accounting field set to 1 will not 
be “tracked” to the creating process. 


At process termination time, any tracked spaces that exist may cause the machine to attempt to 
destroy the existing tracked spaces. If this is done, the destroy attempts would be performed as if an 
MI program issued a Destroy Space (DESS) instruction for each of the existing spaces. 


The purpose of process temporary space accounting is to identify objects which may be “lost” in the 
system (until the next IPL). It should not intentionally be used (by Ml) as a method of cleaning up tem- 
porary space objects at process termination time. The machine does not guarantee that all spaces 
(that should be tracked) will indeed be tracked. Also, if the machine is attempting to destroy tracked 
spaces at process termination time, any failures in the deletion attempts (such as if a space is locked 
to another process) will be ignored (i.e. the space will not be destroyed) and no indication of this is 
presented to the MI user. 


Process temporary space accounting only applies to temporary space objects. A value of 1 for the 
process temporary space accounting field when creating a permanent object will result in a template 
value invalid (hex 3801) exception. This is in spite of the fact that a value of 1 for this field would result 
in the same actions as when creating a permanent object (i.e. the object would not be tracked to the 
process). The exception is presented because this field is undefined for permanent objects. 


Chapter 6. Space Management Instructions 6-7 


Create Space (CRTS) 


The ASP number field specifies the ASP number of the ASP on which the unit is to be allocated. A 
value of 0 indicates an ASP number is not specified and results in the default of allocating the object in 
the system ASP. Allocation on fhe system ASP can only be done implicitly by not specifying an ASP 
number. The only non-zero values allowed are 2 through 16 which specify the user ASP on which the 
space object will be allocated. The ASP number must specify an existing ASP or else an Auxiliary 
Storage Pool number invalid (hex 1CQ9) exception will be signaled. The ASP number field may only be 
specified for creation of a permanent object. The ASP number attribute of an object can be material- 
ized, but cannot be modified. 


Invalid specification of the ASP number attribute results in the signaling of the template value invalid 
(hex 3801) exception. 


The performance class fields provide information allowing the machine to more effectively manage the 
space object considering the overall performance objectives of operations involving the space. The 
unit number field indicates the auxiliary storage unit on which the space should be located, if possible. 


The preferred unit number field which can be specified in the performance class field at object creation 
may not be specified in conjunction with specification of the ASP number attribute. 


The extension offset specifies the byte offset from the beginning of the operand 2 template to the 
beginning of the template extension. An offset value of zero specifies that the template extension is 
not provided. A negative offset value is invalid. A non-zero offset must be a multiple of 16 (to cause 
16 byte alignment of the extension). Except for these restrictions, the offset value is not verified for 
correctness relative to the location of other portions of the create template. 


The largest size needed for space field of the template extension specifies, when nonzero, a value in 
bytes that indicates the largest size that will be needed for the space. This field is different from the 
size of space field which indicates the size for the initial allocation of the space. This field can be used 
to communicate to the machine what the largest size needed for the space will be. Specification of a 
value larger than the maximum size space allowed for this object is invalid and results in signaling of 
the template value invalid (hex 3801) exception. Specification of a nonzero value that is less than the 
size of space field also results in the signaling of the template value invalid (hex 3801) exception. For 
more information on the maximum allowed, see the Limitations topic at the end of the instruction’s 
description. 


Specifying the /argest size of space needed value allows the machine, under certain circumstances, to 
select usage of an internal storage allocation unit which best utilizes the internal addressing resources 
within the machine. Note that the internal storage allocation unit selected can alter the maximum mod- 
ification size of the associated space for the object. However, the machine will always use an internal 
storage allocation unit that will allow for extension of the space to at least the value specified in the 
the largest size of space needed field. The maximum size to which the space can be modified is 
dependent upon specific implementations of the machine and can vary with different machine imple- 
mentations. For more information on the affect of this option, see the Limitations topic at the end of this 
create instruction definition. 


The domain assigned field in the template extension allows the user of this instruction to override the 
domain for this object that would otherwise be chosen by the machine. 


Any value specified for the domain assigned field other than those listed will result in a template value 
invalid exception (hex 3801) being signalled. 
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Limitations: The following are limits that apply to the functions performed by this instruction. 


The maximum size space allowed for this object under any circumstances is limited to 16MB-256 
Bytes. Note that the value specified in largest size of space needed field in the creation template is 
used by the machine as part of the criteria used in selecting the appropriate internal storage allocation 
unit to be used for the storage allocations for the space. 


Authorization Required 
« Insert 
— User profile of object owner 
— Context identified in operand 2 
e« Retrieve 
— Context referenced for address resolution 
e Object control 


— Operand 1 if being replaced 


Lock Enforcement 
e Materialize 
— Contexts referenced for address resolution 
e Modify 
— Context identified in operand 2 
— User profile of object owner 


— Access group identified in operand 2 


Exceptions 
Operands 

Exception 1 2 Other 
02 Access group 

02 object exceeds available space X 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment Xx X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
0A Authorization 

01 unauthorized for operation X 
OE Context operation 

01 duplicate object identification X 
10 Damage encountered 

04 system object damage state X X X 
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Operands 
Exception 1 2 Other 
05 authority verification terminated due to damaged object X ) 
44 partial system object damage X X X 
1A Lock state 
01 invalid lock state X 
1c Machine-dependent exception 
03 machine storage limit exceeded X 
04 object storage limit exceeded X 
09 auxiliary storage pool number invalid X 
20 Machine support 
02 machine check X 
03 function check X 
22 Object access 
01 object not found X X 
02 object destroyed xX X 
03 object suspended xX X 
07 authority verification terminated due to destroyed object X 
08 object compressed X 
24 Pointer specification 
01 pointer does not exist X X . ) 
02 pointer type invalid X X 
Pointer addressing invalid object X 
2E Resource control limit 
01 user profile storage limit exceeded X 
36 Space management 
01 space extension/truncation X 
38 Template specification 
01 template value invalid X 
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Op Code (Hex) Operand 1 
0036 Receiver 


Operand 7: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATS ( 
receiver : space pointer; 
var space object : system pointer 


) 


Operand 2 
Space object 


Materialize Space Attributes (MATS) 


Description: The current attributes of the space object specified by operand 2 are materialized into 


the receiver specified by operand 1. 


The template identified by operand 1 must be 16-byte aligned in the space. The format of the 


materialization is as follows: 


e Materialization size specification 


— Number of bytes provided for materialization 


— Number of bytes available for materialization 


(always 96 for this instruction) 
e Object identification 
— Object type 
— Object subtype 
— Object name 
e Object creation options 
— Existence attribute 


0 = Temporary 
1 = Permanent 


— Space attribute 


0 = Fixed-length 
1 = Variable-length 


— Context 


0 Addressability not in context 
1 = Addressability in context 


— Access group 


0 = Not member of access group 
1 = Member of access group 


— Reserved (binary 0) 
— Initialize space 


0 = Initialize 


Char(8) 
Bin{4) 
Bin(4) 


Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(4) 
Bit 0 


Bit 1 


Bit 2 


Bit 3 


Bits 4-12 
Bit 13 
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1 = Do not initialize 


— Automatically extend space Bit 14 J 
0 = No 
1 = Yes 

— Hardware storage protection level Bits 15-16 


00 = Reference and modify allowed for user state programs 


01 = Only reference allowed for user state programs 
10 = Invalid (undefined) 
11 = No reference or modify allowed for user state programs 
— Reserved (binary 0) Bits 17-31 
e Reserved (binary 0) Char(2) 
e ASP number Char(2) 
e Size of space Bin(4) 
¢ Initial value of space Char(1) 
e Performance class Char(4) 
Bit 0 


— Space alignment 


QO = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, this value must 
be specified for the performance class. 

1 = The space associated with the object is allocated to allow proper alignment of pointers at 


16-byte alignments within the space as well as to allow proper alignment of input/output 
t 


buffers at 512-byte alignments within the space. J 
— Reserved (binary 0) Bits 1-4 
— Main storage pool selection Bit 5 


0 Process default main storage pool is used for object. 
1 = Machine default main storage pool is used for object. 


ll 


— Transient storage pool selection Bit 6 


0 = Default main storage pool (process default or machine default as specified for main 
storage pool selection) is used for object. 
= Transient storage pool is used for object. 


— Block transfer on implicit access state modification Bit 7 


0 = Transfer the minimum storage transfer size for this object. This value is 1 storage unit. 
= Transfer the machine default storage transfer size. This value is 8 storage units. 


— Unit number Bits 8-15 

— Reserved (binary 0) Bits 16-31 
¢ Reserved (binary 0) Char(7) 
e Context System pointer 
e Access group System pointer 


The first 4 bytes that are materialized identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 


of less than 8 causes a materialization length (hex 3803) exception. wd 


The second 4 bytes that are materialized identify the total number of bytes available to be materialized. 
The instruction materializes as many bytes as can be contained in the area specified as the receiver. 
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If the byte area identified by the receiver is greater than that required to contain the information 
requested, then the excess bytes are unchanged. No exceptions (other than the materialization length 
exception described previously) are signaled in the event that the receiver contains insufficient area for 


the materialization. 


See the Create Space instruction for a description of these fields. 


This instruction cannot be used to materialize the public authority specified creation option, the initial 


owner specified creation option, the process temporary space 


accounting creation option, or the tem- 


plate extension which can be specified on space creation. The Materialize Authority instruction can be 


used to materialize the current public authority for the space. 


The Materialize System Object instruc- 


tion can be used to materialize the current owner of the space. 


Authorization Required 
*« Operational or space authority 
— Operand 2 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 


Exception 

06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


0A Authorization 


01 unauthorized for operation 


10 Damage encountered 
04 system object damage state 
0§ authority verification terminated due to damaged object 


44 partial system object damage 


1A Lock state 


01 invalid lock state 


1C Machine-dependent exception 


03 machine storage limit exceeded 


Operands 
1 2 Other 


X X 
X X 
X X 
X X 
X X 
X 

X X X 

X 

X X X 
X 

X 
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Operands 


Exception 1 2 Other 


20 


22 


24 


2e 


36 


38 


Machine support ; ) 


02 machine check Xx 


03 function check Xx 


Object access 


01 object not found X X 


~*~ 
~*~ 


02 object destroyed 
03 object suspended X X 
07 authority verification terminated due to destroyed object X 


08 object compressed X 


Pointer specification 


01 pointer does not exist X X 


x 


02 pointer type invalid X 


03 pointer addressing invalid object X 


Resource control /Jimit 


01 user profile storage limit exceeded X 


Space management 


01 space extension/truncation X 


Template specification 
03 materialization length exception X ) 
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Modify Space Attributes (MODS) 


Op Code (Hex) Operand 1 Operand 2 

0062 System object. Size or Space 
modification tem- 
plate. 


Operand 1: System pointer. 


Operand 2: Binary scalar or character(28) scalar (fixed length). 


ILE access 


MODS1 ( 
var space object : system pointer; 
var size : signed binary 


) 
OR 


MODS2 ( 
var system_object : system pointer; 
var space modification_template : aggregate 


) 


Description: The attributes of the space associated with the system object specified for operand 1 are 
modified with the attribute values specified in operand 2. Operand 1 may address any system object. 


The operand 2 space modification template is specified with one of two formats. The abbreviated 
format, operand 2 specified as a binary scalar, only provides for modifying the size of space attribute. 
The full format, operand 2 specified as a character scalar, provides for modifying the full set of space 
attributes. 


When operand 2 is a binary value, it specifies the size in bytes to which the space size is to be modi- 
fied. The current allocation of the space is extended or truncated accordingly to match as closely as 
possible the specified size. The modified space size will be of at least the size specified. The actual 
size allocated is dependent upon the algorithm used within the specific implementation of the machine. 
If the space is of fixed size, or if the value of operand 2 is negative, or if the operand 2 size is larger 
than that for the largest space that can be associated with the object, the space extension/truncation 
exception is signaled. When operand 2 is a character scalar, it specifies a selection of space attribute 
values to be used to modify the attributes of the space. It must be at least 28 bytes long and have the 
following format: 


¢ Modification selection Char(4) 
— Modify space length attribute Bit O 
0 = No 
= Yes 
— Modify size of space Bit 1 
0 = No 
1 = Yes 
— Modify initial value of space Bit 2 
0 = No 
1 = Yes 
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— Modify performance class 


Q = No 
1 = Yes 


— Modify initialize space attribute 


0 = No 
1 = Yes 


— Reinitialize space 


0 = No 
1 = Yes 


— Modify automatically extend space 


attribute 
Q = No 
1 = Yes 


— Create secondary associated space 


0 = No 
1 = Yes 


— Reserved (binary 0) 
Indicator attributes 

— Reserved (binary 0) 
— Space length 


O = Fixed length 
1 = Variable length 


— Initialize space 


0 Initialize 
1 = Do not initialize 


— Automatically extend space 
0 = No 
1 = Yes 
— Reserved (binary 0) 
— Hardware storage protection level* 


00 = Reference and modify allowed for user state programs 
01 = Only reference allowed for user state programs 

10 = Invalid (undefined) 

11 = No reference or modify allowed for user state programs 


— Reserved (binary 0) 

Maximum size of space* 

Size of space 

Initial value of space 

Performance class 

Reserved (binary 0) 

Secondary associated space number 


Reserved (binary 0) 


Bit 3 


Bit 4 


Bit 5 


Bit 6 


Bit 7 


Bits 8-31 
Char(4) 


Bit O 


Bit 1 
Bit 2 
Bit 3 


Bits 4-14 
Bits 15-16 


Bits 17-31 

Bin(4) 

Bin(4) 

Char(1) 

Char(4) 

Char(1) 

UBin(2) wd 
Char(4) 
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* These fields will be ignored when create secondary associated space is 0. 
The modification selection indicator fields select the modifications to be performed on the space. 


The modify space length attribute modification selection field controls whether or not the space length 
attribute is to be modified. When yes is specified, the value of the space length indicator is used to 
modify the space to be specified fixed or variable length attribute. When no is specified, the space 
length indicator attribute value is ignored and the space /ength attribute is not modified. 


The modify size of space modification selection field controls whether or not the allocation size of the 
space is to be modified. When yes is specified, the current allocation of the space is extended or 
truncated accordingly to match as closely as possible the specified size in the size of space field. The 
modified size will be at least the size specified. The actual size allocated is dependent upon the algo- 
rithm used within the specific implementation of the machine. When no is specified, the current allo- 
cation of the space is not modified and the size of space field is ignored. 


Modification of the size of space attribute for a space of fixed length can only be performed in conjunc- 
tion with modification of the space /ength attribute. In this case, the space length attribute may be 
modified to the same fixed length attribute or to the variable length attribute. An attempt to modify the 
size of space attribute for a space of fixed length without modification of the space length attribute 
results in the signaling of the space extension/truncation (hex 3601) exception. Modification of the size 
of space attribute for a space of variable length can always be performed separately from a modifica- 
tion of the space /ength attribute. 


When the size of space attribute is to be modified, if the value of the size of space field is negative or 
specifies a size larger than that for the largest space that can be associated with the object, the space 
extension/truncation (hex 3601) exception is signaled. 


The modify initial value of space modification selection field controls whether or not the initial value of 
space attribute is to be modified. When yes is specified, the value of the initial value of space field is 
used to modify the corresponding attribute of this space. This byte value will be used to initialize any 
new space allocations for this space due to an extension to the size of space attribute on the current 
execution of this instruction as well as any subsequent modifications. When no is specified, the initial 
value of space field is ignored and the /nitial value of space attribute is not modified. 


The modify performance class modification selection field controls whether or not the performance 
class attribute of the specified system object is to be modified with the values relating to space objects. 
When yes is specified, the value of the performance class field is used to modify the corresponding 
attribute of the specified system object. When no is specified, the performance class attribute of the 
specified system object is not modified. 


The modify initialize space attribute modification selection field controls whether or not the initialize 
space attribute is to be modified. When yes is specified, the value of the initialize space indicator attri- 
bute is used to modify that attribute of the specified space to the specified value. When no is specified, 
the initialize space indicator attribute value is ignored and the /nitialize space attribute is not modified. 


Changing the value of the initialize space attribute only affects whether or not future extensions of the 
space will be initialized or not. That is, it is the state of this attribute at the time of allocation of the 
storage for a space that determines whether that newly allocated storage area will be initialized to the 
initial value specified for the space. Modifications of this attribute subsequent to the allocation of 
storage to a space have no effect on the value of that previously allocated storage area. 


The reinitialize space modification selection field controls whether the storage allocated to the space is 
to be reinitialized in its entirety. When no is specified, the space is not reinitialized. When yes is speci- 
fied, the space is reinitialized. This re-initialization is performed after all other attribute modifications 
which may also have been specified on the instruction have been made. Thus changes to the size of 
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the space, the initial value of the space, etc. will be put into effect and be considered the current attri- 

butes of the space for purposes of the re-initialization. The byte value used for the re-initialization is 

either the current initial value for the space if the initialize space attribute for the space currently speci- J 
fies yes, or a value of hex 00 if the initialize space attribute currently specifies no. 


Note that specifying yes for the reinitialize space modification selection field for a space with current 
attributes of fixed length size Zero results in no operation, because such a space has no allocated 
storage to reinitialize. Also, note that re-initialization of a space will have the side effect of resetting 
partial damage for a space object containing the space if the space object had previously been marked 
as having partial damage. This only applies to space objects; i.e. re-initialization of an associated 
space does not have the side effect of resetting partial damage for the MI object containing it. 


The modify automatically extend space attribute modification selection field controls whether or not the 
automatically extend space attribute is to be modified. When yes is specified, the value of the automat- 
ically extend space indicator attribute is used to modify that attribute of the specified space to the 
specified vatue. When no is specified, the autmatically extend space indicator attribute value is ignored 
and the automatically extend space attribute is not modified. The automatically extend space attribute 
can only be specified as yes when the space /ength attribute for the space is already variable length, or 
when the space /ength attribute is being modified to variable length. Invalid specification of the auto- 
matically extend space attribute results in the signaling of the invalid space modification (hex 3602) 
exception. 


Modification to or from the state of a space being fixed length of size zero can not be performed for the 
following objects: 


Class of service description 


Controller description F 
Cursor ») 
Data space 


Logical unit description 
Mode description 
Network description 
Space 
| Program (when attempted while in user state on a security level 40 or higher system). 


If such a modification is attempted for these objects, the invalid space modification (hex 3602) exception 
is signaled. 


Specifying yes for the modify performance class modification selection field is only allowed when the 
space to be modified is a fixed length space of size zero. This modification may be specified in con- 


junction with other modifications. Only bit 0 of the performance class field is used to modify the per- 
formance class attribute of the specified system object. A bit value of zero requests that the start of 
the space storage provide 16-byte multiple (pointer) machine address alignment. A bit value of one 
requests that the start of the space storage provide 512-byte multiple (buffer) machine address align- 
ment. Bits 1 through 31 are ignored. Specifying yes for the modify performance class modification 
selection field when the space to be modified is not a fixed length space of size zero results in the 
signaling of the invalid space modification (hex 3602) exception. 


| The create secondary associated space field indicates if a secondary associated space is to be created 

| for the object. All the indicator attributes and size and value fields are used for this create. The sec- 

| ondary associated space to be created is indicated by the secondary associated space number field. If S 
| the specified space already exists, the invalid space modification (hex 3602) exception is signalled. 

| When this bit is set to yes, all other modification selection bits are ignored. 


Chapter 6. Space Management Instructions 6-18 


Modify Space Attributes (MODS) 


specifying the largest size of space needed value allows the machine. under certain circumstances, to 
select usage of an internal storage allocation unit which best utilizes the internal addressing resources 
within the machine. Note that the internal storage allocation unit selected can alter the maximum mod- 
ification size of the associated space for the object. However, the machine will always use an internal 
storage allocation unit that will allow for extension of the space to at least the value specified in the 
the largest size of space needed field. The maximum size to which the space can be modified is 
dependent upon specific implementations of the machine and can vary with different machine imple- 
mentations. 


The secondary associated space number field is used to indicate which secondary space is to be 
created or modified. When this field is zero, the primary associated space of the space object is modi- 
fied. if this field is not zero and no secondary associated spaces are allowed for the object, the scalar 
value invalid (hex 3203) exception will be signalled. 


A fixed length space of size zero is defined by the machine to have no internal storage allocation. Due 
to this, a modification to or from this state is, in essence, the same as a destroy or create for the space 
associated with the specified system object. The effect of modifying to this state is similar to 
destroying the associated space in that address references to the space through previously set 

| pointers will result in signaling of the object destroyed exception. When a primary associated space is 

| destroyed by using this method, any secondary associated spaces for the object are also destroyed. 
Additionally, an attempt to set a space pointer to the space associated with the specified system object 
through the Set Space Pointer from Pointer instruction will result in the signaling of the invalid space 
reference (hex 0605) exception. To the contrary, modifying the space attributes from this state is 
similar to creating an associated space in that the Set Space Pointer from Pointer instruction can be 
used to set a space pointer to the start of a storage within the associated space and the allocated 
space storage can be used to contain space data. 


The extension and truncation of a space is always by an implementation-defined multiple of 256 bytes. 
Qe This means that if, for example, the implementation defined multiple is 2 (or 512 bytes), any modifica- 
tion of the space size will be in increments of 512 bytes. 


Authorization Required 
e Object management 

— Operand 1 
« Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢« Materialize 
— Contexts referenced for address resolution 
¢« Object control 
— Operand 1 (when operand 2 is binary) 
¢ Modify 
— Operand 1 (when operand 2 is character) 


Events 


0002 Authorization 
Cc 0101 Object authorization violation 


OO0OC Machine resource 
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0201 Machine auxiliary storage threshold exceeded 
0202 User auxiliary storage pool threshold exceeded 
0203 User auxiliary storage pool overflow 

0204 Asp unprotected space overflow 

0501 Machine address threshold exceeded 


O00D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 


0017 Damage set 
0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 
05 invalid space reference 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


0A Authorization 


01 unauthorized for operation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1A Lock state 


01 invalid lock state 


1C Machine-dependent exception 
03 machine storage limit exceeded 


04 object storage limit exceeded 


20 Machine support 
02 machine check 


03 function check 
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Operands 
1 2 Other 


X X 
X X 
X X 
X 
X X 
X X 
X 
X X X 
X 
X X X 
X 
X 
X 
X 
X 
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Exception 


22 


24 


2E 


32 


36 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Program creation 

06 invalid operand type 

07 invalid operand attribute 

08 invalid operand value range 
0A invalid operand length 

OC invalid operand odt reference 


0D reserved bits are not zero 


Resource control limit 


01 user profile storage limit exceeded 


Scalar Specification 


03 scalar value invalid 


Space management 
01 space extension/truncation 


02 invalid space modification 
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Operands 
1 2 
X X 
X X 
X X 
X X 
X 
X 
X X 
X X 
X X 

X 
X X 
X X 
X 

X 
X X 
X X 
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Chapter 7. Heap Management Instructions 


This chapter describes the instructions used for heap management. These instructions are in alpha- 
betic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 


Allocate Heap Space Storage (ALCHSS)  ......... 0... ce 7-3 
Create Heap Space(CRIHS) <scces weee ec awe deed Saeed HAWS Awe SEES PSS 7-6 
Destroy Heap Space (DESHS) as nwe ae eC Ga SO 6 eS ee 8 ee eee 7-11 
Free Heap Space Storage (FREHSS) .......... 0.0. 0. ec ee 7-13 
Free Heap Space Storage From Mark (FREHSSMK) ............. 0000 eee eee eee 7-15 
Materialize Heap Space Attributes (MATHSAT) ...... 0... 2... ee en 7-17 
Reallocate Heap Space Storage (REALCHSS) .......... 0.00. eee eee ee ee 7-22 
Set Heap Space Storage Mark (SETHSSMK) ........0.. 0.0.00 eee ee ee es 7-25 
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Allocate Heap Space Storage (ALCHSS) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0383 Space allocation Heap Identifier Size of space allo- 
cation 


Operand 1: Space pointer. 
Operand 2: Binary(4) scalar or null. 


Operand 3: Binary(4) scalar. 


ILE access 


ALCHSS ( 
heap_identifier : signed binary; 
size_of_space_allocation : signed binary 
) : space pointer /* space_allocation */ 


Description: A heap space storage allocation of at least the size indicated by operand 3 is provided 
from the heap space indicated by operand 2. The operand 1 space pointer is set to address the first 
byte of the allocation which will begin on a boundary at least as great as the minimum boundary speci- 
fied when the heap space was created. 


Each allocation associated with a heap space provides a continuum of contiguously addressable bytes. 
Individual allocations within a heap space have no addressability affinity with each other. The contents 
of the heap space allocation are unpredictable unless initialization of heap allocations was specified 
when the heap space was created. 


Simultaneous operations against a heap space from multiple processes is not supported and may 
produce unpredictable results. 


The maximum single allocation allowed is determined by the maximum single allocation size specified 
when the heap space was created. The maximum single allocation possible is 16M-64K bytes. 


It is the responsibility of the using program to see that only the amount of heap space storage 
requested is used. Reference to heap space storage outside the bounds of the requested space will 
produce unpredictable results. The exact address returned must be supplied to the Free Heap Space 
Space Storage (FREHSS) instruction when the user has completed use of the heap space storage. 


A default heap space (heap identifier value of 0) is automatically available in each activation group 
without issuing a Create Heap Space (CRTHS) instruction. The default heap space is created when the 
first Allocate Heap Space is issued against the default heap space. When operand 2 is null, the default 
heap space (heap identifier of 0) provides the allocation. 


The machine supplied attributes of the default heap space are as follows: 
e Maximum single allocation size is 16M - 64K bytes. 


e Minimum boundary requirement is a 16 byte boundary. 


¢« The creation size advisory is 4KB unless the size of the allocation request dictates a larger cre- 
ation size be used. 


e« The extension size advisory is 4KB unless the size of the allocation request dictates a larger exten- 
sion size be used. 
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¢ Domain is determined from the state of the program issuing the instruction. 


¢ Normal allocation strategy. © 
e A heap space mark is not allowed. 


¢ The transfer size is 1 storage unit. 


« The process access group membership advisory value is taken from the activation group. Default 
activation groups get this value from the attribute specified on the Initiate Process (INITPR) instruc- 
tion. Other activation groups get this value from the attribute specified on the Create Bound 
Program (CRTBPGM) instruction for the program which initiated the activation group. 


e Heap space storage allocations are not initialized to the allocation value. 


e Heap space storage allocations are not overwritten to the freed value after being freed. 


Neither operand 2 nor 3 is modified by the instruction. 


Events 


OOOC Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


000D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 
0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 

06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 
08 Argument/parameter 


01 parameter reference violation 


10 Damage encountered 


Operands 
1 2 3 Other 


x KX XK KK 
x xX K XK 
x KK XK 
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Exception 


20 


24 


04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 

Pointer specification 

01 pointer does not exist 

02 pointer type invalid 

03 Pointer addressing invalid object 


Domain specification 


01 Domain Violation 


Heap specification ; 
01 Invalid Heap Identifier 
03 Heap Space Full 

04 Invalid Size Request 
05 Heap Space Destroyed 
06 Invalid Heap Condition 


Operands 

1 2 3 Other oie 

X X X X | j 
X 


X X 
X X X 

X 

X 
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Create Heap Space (CRTHS) 


Op Code (Hex) Operand 1 Operand 2 
03B2 Heap Identifier Heap Space cre- 
ation template 


Operand 7: Binary(4) variable scalar 


Operand 2: Space pointer 


ILE access 


CRTHS ( 
var heap_ identifier : signed binary; 
creation template : space pointer 


Description: A heap space is created with the attributes supplied in the heap space creation template 
specified by operand 2. The heap space identifier used to perform allocations and marks against the 


heap space is returned in operand 1. 


The heap identifier returned in operand 1 represents the heap space. This identifier is used for the 


Allocate Heap Space Storage (ALCHSS), Destroy Heap Space (DESHS), Set Heap Space Storage Mark 


(SETHSSMK) and Materialize Heap Space Attributes (MATHSAT) instructions. 


The heap space creation template identified by operand 2 must be 16-byte aligned in the space. 
Operand 2 is not modified by the instruction. 


The following is the format of the heap space creation template: 


e Reserved (binary 0) Char(8) 
* Maximum single allocation UBin(4) 
¢ Minimum boundary requirement UBin(4) 
« Creation size UBin(4) 
¢ Extension size UBin(4) 
¢ Domain/Storage protection Bin(2) 


Hex 0000 = System should chose the Domain 
Hex 0001 = The heap space domain. should be “Common User’ 
Hex 8000 = The heap space domain should be "Common System” 


¢ Heap space creation options Char(6) 
— Allocation strategy Bit O 
0 Normal allocation strategy 


1 Force process space creation on each allocate 

— Heap Space Mark Bit 1 
0 = Allow heap space mark 
1 = Prevent heap space mark 

— Block transfer Bit 2 


0 = Transfer the minimum storage transfer size. 
This value is 1 storage unit. 
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1 = Transfer the machine default storage transfer size. 
This value is 8 storage units. 


— Process access group member Bit 3 J 


Q = Do not create the heap space in the PAG. 
1 Create the heap space in the PAG. 


— Allocation initialization Bit 4 


0 = Do not initialize allocations. 


1 = Initialize allocations. 
— Overwrite freed allocations Bit 5 

0 = Do not overwrite freed allocations. 

1 = Overwrite freed allocations. 
— Reserved (binary 0) Bits 6-7 
— Allocation value Char(1) 
— Freed value Char(1) 
— Reserved (binary 0) Char(3) 

« Reserved (binary 0) Char(64) 


The maximum single allocation of any single allocation from the heap space is useful for controlling the 

use of the heap space and may also improve performance for some cases when the machine can opti- 

mize access based on this attribute. The minimum value that can be specified is 4 bytes, and the 

maximum value that can be specified is 16M-64K bytes. If zero is specified, the default value of 

16M-64K bytes will be used. Values outside the range indicated will cause a template value invalid i 


(hex 3801) exception. J 


The minimum boundary alignment associated with any allocation from the heap space can be specified 
in the template. The minimum value that can be specified is a 4 byte boundary alignment. The 
maximum boundary alignment that can be specified is a 512 byte boundary alignment. If zero is speci- 
fied, a default of a 16 byte boundary will be used. The minimum boundary alignment will be rounded 
up to a power of 2. Values outside the range indicated will cause a template value invalid (hex 3801) 
exception. 


The creation size of the heap space can be specified in the template. If zero is specified the system 
will compute a default value. The minimum value that can be specified is 512 bytes. The maximum 
value that can be specified is 16M-1K bytes. The value specified will be rounded up to a storage unit 
boundary. Values outside the range indicated will cause a template value invalid (hex 3801) exception. 
This is an advisory value only. The machine may decide to override the value specified based on 
system resource constraints. 


The extension size of the heap space can be specified in the template. If zero is specified the system 
will compute a default value. The minimum value that can be specified is 512 bytes. The maximum 
value that can be specified is 16M-1K bytes. The value specified will be rounded up to a storage unit 
boundary. Values outside the range indicated will cause a template value invalid (hex 3801) exception. 
This is an advisory value only. The machine may decide to override the value specified based on 
system resource constraints. 


The domain/storage protection field in the template allows the user of this instruction to override the 

domain for the heap space that would otherwise be chosen by the machine. The domain/storage pro- 

tection attribute can be used to restrict access to the contents of the heap space by user state pro- S ' 
grams. It is possible to limit the access of the heap space by user state programs into 1 of two levels: 
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« No storage references (all storage references, modifying or non-modifying yield a 
domain/protection violation (hex 4401) exception). This is Common System. 


e Full access (both modifying and non-modifying storage references are allowed). This is Common 
User. 


Only a system state process can specify a heap space to be created with a domain of Common 
System. If a user state program attempts to specify the domain/storage protection as Common System, 
a template value invalid (hex 3801) exception will be signaled. Any value other than the ones listed will 
cause a template value invalid (hex 3801) exception to be signaled. 


The normal allocation strategy as defined by the machine will be used unless the force process space 
creation on each allocation attribute is indicated. This option should only be used in unusual situ- 
ations, such as when necessary for debug of application problems caused by references outside an 
allocation. 


The heap space mark attribute can be used to prevent the use of the Set Heap Space Storage Mark 
(SETHSSMkK) and Free Heap Space Storage from Mark (FREHSSMK) instructions on a heap space. 


Block transfer on a heap space is used to increase the performance of a heap space based on prior 
Knowledge of the program creating the heap space on how that heap space will be used. This attri- 
bute is used only when the heap space is not a member of a process access group (PAG). 


A heap space can be created as a process access group (PAG) member of the currently executing 
process, if specified by the prcoess access group member It is possible for the PAG to overflow at 
which point any requested heap space creations or extensions will not reside in the PAG. Thus the 
specification to have the heap space as a member of the PAG is only an advisory which the machine 
may decide to override. 


The allocation initialization field in the template allows the user of this instruction to specify that all 

storage allocations from the heap space being created will be initialized to the allocation value sup- 
plied in the template. If the user chooses not to initialize heap space storage allocations, the initial 
value of heap space storage allocations is unpredictable but will not expose data produced by a dif- 
ferent user profile. 


The overwrite freed allocations field in the template allows the user of this instruction to specify that all 
heap space storage allocations upon being freed will be overwritten with the the freed value supplied 
in the template. If the user chooses not to overwrite heap space storage allocations when freed, the 
contents of the freed allocations will be unaltered. 


A default heap space (heap identifier value of 0) is automatically available in each activation group, 
without issuing a Create Heap Space (CRTHS) instruction. The default heap space is created on the 
first allocation request of the default heap space. See Allocate Heap Space Storage (ALCHSS) for a 
description of the default heap space. 


A heap space is scoped to an activation group, thus the maximum life of a heap space is the life of the 
activation group in which the heap space was created. A heap space can only be destroyed from 
within the activation group in which it was created. 


™ 


Simultaneous operations against a heap space from multiple processes is not supported and may 
produce unpredictable results. 
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Limitations: The following are limits that apply to the functions performed by this instruction. 


The amount of heap space storage that can be allocated for a single heap space is 4G-512K bytes. 
Due to fragmentation a heap space may grow to 4GB-512KB without having 4GB-512KB of outstanding 


heap space storage allocations. 


The maximum allocation size of any single allocation from the heap space is limited to 16MB-64K 


bytes. A smaller maximum allocation size can be specified. 


Events 


OO0OC Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


OOOD Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 
0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 
06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1C Machine-dependent exception 
03 machine storage limit exceeded 


04 object storage limit exceeded 


Operands 
1 2 Other 


X X 

X X 

X X 

X X 

X X 

X X X 
X 

X X X 
X 
X 
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Exception 


20 


24 


38 


Machine support 
02 machine check 


03 function check 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 Pointer addressing invalid object 


Template specification 


01 template value invalid 


Domain specification 


01 Domain Violation 


Create Heap Space (CRTHS) 


Operands 
1 2 Other 


X 
X 


X X 
X X 
X 
X 
X X 
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Destroy Heap Space (DESHS) 


Destroy Heap Space (DESHS) 


Op Code (Hex) Operand 1 
03B1 Heap Identifier 


Operand 1: Binary(4) variable scalar. 


ILE access 


DESHS ( 
var heap identifier : signed binary 


Description: This instruction destroys and removes from the current activation group the heap space 
specified by the heap identifier in operand 1. Subsequent use of this heap identifier within the acti- 
vation group will result in an invalid identifier (hex 4501) exception. The heap identifier was returned 
on the Create Heap Space (CRTHS) instruction. An attempt to destroy the default heap space (heap 
identifier value of 0) will result in an invalid request (hex 4502) exception. 


Space pointer references to heap space allocations from a destroyed heap space will cause unpredict- 
able results. 


All heap spaces are implicitly destroyed when the activation group in which they were created is 
destroyed. 


Operand 1 is not modified by the instruction. 


Events 


OOOC Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


O00D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 

0401 System object damage set 

0801 Partial system object damage set 
Exceptions 


Operands 
Exception 1 Other 
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Exception 


06 


08 


10 


1c 


20 


24 


45 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Domain specification 


01 Domain Violation 


Heap specification 
01 Invalid Heap Identifier 
02 Invalid Request 
05 Heap Space Destroyed 
06 Invalid Heap Condition 


Destroy Heap Space (DESHS) 


Operands 

1 Other 

X 

X 

X 

X 

X 

X X 
X 

X X 
X 
X 
X 

X 

X 

X 

X 

X 
X 

X X 
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Free Heap Space Storage (FREHSS) 


Free Heap Space Storage (FREHSS) 


Op Code (Hex) . Operand 1 
03B5 Space allocation 


Operand 7: Space pointer. 


ILE access 


FREHSS ( 
Space_allocation : space pointer 
) 


Description: The heap space storage allocation beginning at the byte addressed by operand 1 is de- 
allocated from the heap space which supplied the allocation. De-allocation makes the storage avail- 
able for reuse by subsequent Allocate Heap Space Storage (ALCHSS) instructions. The entire space 
allocation is de-allocated; partial de-allocation is not supported. A free of heap space storage can be 
performed without regard to the activation group in which it was allocated, as long as the allocation 
was done by the same process. 


Operand 1 must be exactly equal to the space pointer that was returned by some previous Allocate 
Heap Space Storage (ALCHSS) or Reallocate Heap Space Storage (REALCHSS) instruction. If it is not, 
an invalid request (hex 4502) exception will be signaled. 


Subsequent references to space allocations which have been freed cause unpredictable results. 


FREHSS will signal a domain violation (nex 4401) exception if a program running user state attempts to 
de-allocate heap space storage in a heap space with a domain of Common System. 


Operand 1 is not modified by the instruction. 


Events 


QOOC Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


OQ00D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 


0401 System object damage set 
0801 Partial system object damage set 
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CC 


Exceptions 


Exception 


06 


08 


10 


1C 


20 


24 


45 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 Pointer addressing invalid object 


Domain specification 


01 Domain Violation 


Heap specification 
02 Invalid Request 
05 Heap Space Destroyed 
06 Invalid Heap Condition 


Free Heap Space Storage (FREHSS) 


Operands 

1 Other 

X 

X 

X 

X 

X 

X X 
X 

X X 
X 
X 
X 

X 

X 

X 

X 
X 

X X 
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Free Heap Space Storage From Mark (FREHSSMK) 


Free Heap Space Storage From Mark (FREHSSMK) 


Op Code (Hex) Operand 1 
03B9 Mark Identifier 


Operand 1: Space pointer data object. 


ILE access 


FREHSSMK ( 
var mark_identifier : space pointer 


) 


Description: All heap space allocations which have occurred from the heap space since it was 
marked, with the mark identifier supplied in operand 1, are freed. This may include heap space 


storage marked by intervening Set Heap Space Storage Mark (SETHSSMkK) instructions. The mark 


identifier specified in operand 1 and all mark identifiers obtained since the heap space was marked by 
operand 1 are cleared from the heap space. An attempt to free heap space storage from a mark that 
has already been cleared by a previous FREHSSMK instruction will result in an invalid identifier (hex 
4507) exception. A free of heap space storage can be performed without regard to the activation group 
in which it was allocated, as long as the allocation was done by the same process. 


FREHSSMK will signal a domain violation (hex 4401) exception if a program running user state 


attempts a free heap space storage from mark for a heap space with a domain of Common System. 


Operand 1 is not modified by the instruction. 


Events 


OO0O0C Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


000D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 
0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 


Operands 
1 Other 
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Free Heap Space Storage From Mark (FREHSSMK) 


Exception 


06 


08 


10 


1c 


20 


24 


45 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Machine-dependent exception 
03 machine storage limit exceeded 
04 object storage limit exceeded 


09 auxiliary storage pool number invalid 


Machine support 
02 machine check 


03 function check 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 Pointer addressing invalid object 


Domain specification 


01 Domain Violation 


Heap specification 
02 invalid Request 
05 Heap Space Destroyed 
06 Invalid Heap Condition 
07 Invalid Mark Identifier 


Operands 

1 Other 

X 

X 

X 

Xx 

X 

X X 
X 

Xx X 
X 
X 
X 

X 

X 

X 

X 
X 

X X 

X 
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Materialize Heap Space Attributes (MATHSAT) 


Materialize Heap Space Attributes (MATHSAT) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 J 
03B7 Materialize tem- Heap identifier Attribute Selection 
plate template 


Operand 1: Space pointer. 
Operand 2: Space pointer. 


Operand 3: Character(1) scalar (fixed length). 


ILE access 
MATHSAT ( 
materialize template : space pointer 
heap_identifier_template : space pointer 
var attribute selection : aggregate 


Description: This instruction will materialize the information selected by operand 3 for the heap space 
specified by operand 2 and return the selected information in the template indicated by operand 1. 
Operand 3 can have three possible values: 
e Hex 00 - Return heap space attributes 
e Hex 01 - Return heap space attributes and mark information. 2 


e Hex 02 - Return heap space attributes, mark information and allocation information. 
Any value for operand 3 other than those listed will cause a scalar value invalid (3203) exception. 
The heap space attributes template identified by operand 1 must be 16-byte aligned in the space. 


If operand 3 is equal to hex 00, then only the heap space attributes template information is returned. 
The format of the attributes template information is as follows (see the Create Heap Space instruction 
for a description of these fields): 


e Template size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 
¢ Maximum single allocation UBin(4) 
¢ Minimum boundary requirement UBin(4) 
¢ Creation size UBin(4) 
¢ Extension size UBin(4) 
¢ Domain Bin(2) 


Hex 0001 = The heap space domain is “Common User” 
Hex 8000 = The heap space domain is “Common System 


” 


¢ Heap space creation options Char(6) 


— Allocation strategy Bit 0 


O = Normal allocation strategy 
1 = Force implicit space creation on each allocate 
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Materialize Heap Space Attributes (MATHSAT) 


— Heap Space Mark Bit 1 
OQ = Allow heap space mark 
1 = Prevent heap space mark 
— Block transfer Bit 2 
O = Transfer the minimum storage transfer size. 
This value is 1 storage unit. 
1 = Transfer the machine default storage transfer size. 
This value is 8 storage units. 
— Process access group member Bit 3 
0 = Do not create the heap space in the PAG. 
1 = Create the heap space in the PAG. 
— Initialization allocations Bit 4 
0 = Do not initialize allocations. 
1 = Initialize allocations. 
— Overwrite freed allocations Bit 5 
0 = Do not overwrite freed allocations. 
1 = Overwrite freed allocations. 
— Reserved (binary 0) Bits 6-7 
— Allocation value Char(1) 
— Freed value | Char(1) 
— Reserved (binary 0) Char(3) 
e Reserved (binary 0) Char(64) 
e Current number of outstanding allocations UBin(4) 
e Total number of reallocations UBin(4) 
e« Total number of frees UBin(4) 
¢« Total number of allocations UBin(4) 
¢ Maximum number of outstanding allocations UBin(4) 
¢« Size of the heap space in pages UBin(4) 
e Number of outstanding marks UBin(4) 
¢« Total number of extensions UBin(4) 


The first 4 bytes that are materialized identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes a materialization length (hex 3803) exception. 


The second 4 bytes that are materialized identify the total number of bytes available to be materialized. 
The instruction materializes as many bytes as can be contained in the area specified as the receiver. 

If the byte area identified by the receiver is greater than that required to contain the information 
requested, then the excess bytes are unchanged. No exceptions (other than the materialization length 
exception described previously) are signaled in the event that the receiver contains insufficient area for 
the materialization. 


If operand 3 is equal to hex 01, then the mark template information is added to the heap space attri- 
butes template information. The mark template information is repeated for the number of outstanding 
marks. This information follows the heap space attributes template information. The format of the 


mark template information is as follows: 
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Materialize Heap Space Attributes (MATHSAT) 


e Mark template information 


— Mark identifier Space pointer J 


Given the list of mark identifiers with a mark identifier being entry N and a allocation belonging to 
mark identifier N, that allocation also belongs to mark identifier N-X, where X has values 1 to N-1 for 
all N> 1. 


If operand 3 is equal to hex 02, then the allocation template information is added to the heap space 
attributes and mark template information. The allocation template information is repeated for current 
number of outstanding allocations. This information follows the mark information template. 


e Allocation template Char(48) 
— Allocation address Space pointer 
— Mark identifier Space pointer 
— Allocation size UBin(4) 
— Reserved Char(12) 


lf mark identifier is null, this allocation is not associated with any mark. [f it is not null it contains the 
most recent mark identifier to which the allocation belongs. 


The heap identifier template identified by operand 2 must be 16-byte aligned in the space. The format 
of the template specified by operand 2 is as follows: 


¢ Heap Identifier Template ‘ Char(8) 
— Activation Group Mark identifier UBin(4) 
f. 
— Heap identifier UBin(4) -) 


The activation group mark identifier may be zero, indicating the heap space specified by the heap iden- 
tifier is in the current Activation Group. 


MATHSAT will signal an activation group access violation (hex 2C12) exception if a program attempts 
to materialize heap space attributes of a heap space in an activation group to which the program does 
not have access. 


Operands 1, 2 and 3 are not modified by the instruction. 


Events 


O0O0C Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


OO00D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 
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Materialize Heap Space Attributes (MATHSAT) 


0017 Damage set 
0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 

06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1¢C Machine-dependent exception 
03 machine storage limit exceeded 
04 object storage limit exceeded 


09 auxiliary storage pool number invalid 


20 Machine support 
02 machine check 


03 function check 


24 Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 Pointer addressing invalid object 


2C Program execution 
12 Activation group access violation 


13 Activation group not found 


32 Scalar specification 


03 Scalar value invalid 


38 Template specification 


03 Materialization length 


44 Domain specification 


01 Domain Violation 


45 Heap specification 
01 Invalid Heap Identifier 


Operands 
1 2 3 Other 


x KK OK 
x KK OK 
x KK K 


X 
X 
X 
X 
X 


X X 
X 
X 

X 

X 

X X X 
X 
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| 
| Exception 

| 02 Invalid Request 
| 

| 


05 Heap Space Destroyed 
06 Invalid Heap Condition 


Materialize Heap Space Attributes (MATHSAT) 


Operands 
1 2 3 Other 


: J 
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Reallocate Heap Space Storage (REALCHSS) 


Op Code (Hex) Operand 1 Operand 2 
03BA Space allocation Size of space real- 
location 


Operand ?: Space pointer. 


Operand 2: Binary(4) scalar. 


ILE access 


REALCHSS ( 
Space allocation : space pointer; 
size_of_space_reallocation : signed binary 
) : space pointer /* space_reallocation */ 


Description: A new heap space storage allocation of at least the size indicated by operand 2 is pro- 
vided from the same heap space as the original allocation, which is indicated by operand 1. The 
operand 1 space pointer is set to address the first byte of the new allocation, which will begin on a 
boundary at least as great as the minimum boundary specified when the heap space was created. 


Each allocation associated with a heap space provides a continuum of contiguously addressable bytes. 
Individual allocations within a heap space have no addressability affinity with each other. 


The maximum single allocation allowed is determined by the maximum single allocation size specified 
when the heap space was created. The maximum single allocation possible is 16M-64K bytes. 


Storage that is reallocated maintains the same mark/release status as the original allocation. If the 
original allocation was marked, the new allocation carries the same mark and will be released by a 
Free Heap Space Storage from Mark (FREHSSMK) which specifies that mark identifier. 


The original heap space storage allocation will be freed. Subsequent references to the original allo- 
cation will cause unpredictable results. 


The contents of the original allocation are preserved in the following fashion: 


¢ If the new allocation size is greater than the original allocation size, the entire contents of the ori- 
ginal allocation will appear in the new allocation. The contents of the rest of the new allocation are 
unpredictable unless initialization of heap allocations was specified when the heap space was 
created. 


e If the new allocation size is less then or equal to the the original allocation size, the new allocation 
will contain at least as much of the original allocation contents as the new allocation size allows. 


REALCHSS will signal a domain violation (hex 4401) exception if a program running user state attempts 
to reallocate heap space storage in a heap space with a domain of Common System. 


Operand 2 is not modified by the instruction. 


Events 


OOOC Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 
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Reallocate Heap Space Storage (REALCHSS) 


QO00D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 
0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 

06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1C Machine-dependent exception 


03 machine storage limit exceeded 


20 Machine support 
02 machine check 


03 function check 


24 Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 Pointer addressing invalid object 


44 Domain specification 


01 Domain Violation 


45 Heap specification 
02 Invalid Request 


Operands 
1 2 Other 


X X 
X X 
X X 
X X 
X X X 
X X X 
X 
X X X 
X 
X 
X 
X X X 
X X X 
X 
X X 
X 
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Reallocate Heap Space Storage (REALCHSS) 


| Operands 

| Exception 1 2 Other 

| 03 Heap Space Full X 
& | 04 Invalid Size Request X 

| 05 Heap Space Destroyed X 

| 06 Invalid Heap Condition X X X 
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Set Heap Space Storage Mark (SETHSSMK) 


Op Cade (Hex) Operand 1 Operand 2 
03B6 Mark Identifier Heap Identifier 


Operand 1: Space pointer data object. 


Operand 2: Binary(4) scalar. 


ILE access 


SETHSSMK 
var mark_identifier : space pointer; 


var heap_identifier : signed binary 


) 


Description: The heap space identified by operand 2 is marked and the mark identifier is returned in 
Operand 1. 


Marking a heap space allows a subsequent Free Heap Space Storage from Mark (FREHSSMk) instruc- 
tion, using the mark identifier returned in operand 1, to free all outstanding allocations that were per- 
formed against the heap space since the heap space was marked with that mark identifier. This 
relieves the user of performing a Free Heap Space Storage (FREHSS) for every individual heap space 
allocation. 


A heap space may have multiple marks. 


The heap identifier specified in operand 2 is the identifier that was returned on the Create Heap Space 
(CRTHS) instruction. An attempt to mark the default heap space (heap identifier value of 0) will result 
in a invalid request (hex 4502) exception. An attempt to mark a heap space that has been created to 
not allow a Set Heap Space Storage Mark will result in a invalid request (hex 4502) exception. 


Operand 2 is not modified by the instruction. 


Events 


Q00C Machine resource 
0201 Machine auxiliary storage threshold exceeded 
0501 Machine address threshold exceeded 


O00D Machine status 
0101 Machine check 
0401 Auxiliary storage device requires service 


0010 Process 
0701 Maximum processor time exceeded 
0801 Process storage limit exceeded 


0016 Machine observation 
0101 Instruction reference 
0401 Domain violation 
0402 Hardware storage violation 


0017 Damage set 
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Set Heap Space Storage Mark (SETHSSMK) 


0401 System object damage set 
0801 Partial system object damage set 


Exceptions 


Exception 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 
06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1C Machine-dependent exception 
03 machine storage limit exceeded 
04 object storage limit exceeded 


09 auxiliary storage pool number invalid 


20 Machine support 
02 machine check 


03 function check 


24 Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 Pointer addressing invalid object 


44 Domain specification 


01 Domain Violation 


45 Heap specification 
01 Invalid Heap Identifier 
02 Invalid Request 
03 Heap Space Full 
05 Heap Space Destroyed 
06 Invalid Heap Condition 


Operands 
1 2 Other 
X X 
X X 
X X 
X X 
X X 
X X X 
X 
X X X 
X 
X 
X 
X 
X 
X X 
X X 
X 
X X 
X 
X 
X 
X 
X X X 
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Program Management Instructions 


Chapter 8. Program Management Instructions 


This chapter describes all instructions used for program management. These instructions are in alpha- 
betic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary” 


Materialize Bound Program (MATBPGM) ............ 0.000. eee ee 8-3 
Materialize Program {(MATPG) ss. ca cetdeed Oe e ie we RO a we Sa eS eS Sa we 8-24 
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Materialize Bound Program (MATBPGM) 


Op Code (Hex) Operand 1 Operand 2 
02C6 Materialization Bound Program or 
request template Bound Service 
Program 


Operand 1: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATBPGM ( 
request_template : space pointer 
var bound program : system pointer 


Description: The bound program or bound service program identified by operand 2 is materialized 
according to the specifications provided by operand 1. 


Operand 2 is a system pointer that identifies the bound program or bound service program to be mate- 
rialized. If Operand 2 does not refer to a program object, an object not eligible for operation (hex 2403) 
exception will be signaled. If Operand 2 refers to a program, but not to a bound program or bound 
service program, then a program not eligible for operation (hex 220A) exception will be signaled. 


The values in the materialization relate to the current attributes of the materialized bound program. 
Components are the materializable parts of a bound program or bound service program. Components 
may not be available for materialization because they were not encapsulated during bound program 
creation. Other components may not be available for materialization because they contain no data. 


Note: The bound program materialization request template takes the form of a variable length array of 
materialization requests. 


¢ Template size specification Char(8) 

— Number of bytes provided UBin(4) 

— Reserved (binary 0) Char(4) 

e Number of materialization requests UBin(4) 

¢ Reserved (binary 0) Char(4) 

¢ Array of materialization requests Char(") 
— Receiver Space pointer 

— Bound Program materialization options Char(4) 

- General Bound Program materialization options Char(2) 

e General bound program information Bit 0 


0 = Do not materialize 
1 = Materialize 


1 Reserved for IBM Internal Use Only. If used, unpredictable results may occur. 
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e Reserved' Bit 1 
e Program copyright Strings Bit 2 
0 = Do not materialize 
1 = Materialize 
e Bound service programs information Bit 3 
0 = Do not materialize 
1 = Materialize 
e Bound modules information Bit 4 
0 = Do not materialize 
1 = Materialize 
e Bound program string directory component Bit 5 
0 = Do not materialize 
1 = Materialize 
e Bound program limits Bit 6 
0 = Do not materialize 
1 = Materialize 
e Reserved' Bits 7-11 
¢ Activation group data imports Bit 12 
0 = Do not materialize 
1 = Materialize 
e Activation group data exports Bit 13 
0 = Do not materialize 
1 = Materialize 
e Reserved (binary 0) Bits 14-15 
- Specific Bound Program materialization options Char(1) 
e Specific bound program information Bit O 


0 = Do not materialize 


1 = Materialize if the program is a bound program and not a bound service program. 


e Reserved (binary 0) Bits 1-7 
- Specific Bound Service Program Char(1) 
- Materialization options 
e Reserved (binary 0) Bit O 
e Signatures information Bit 1 
0 = Do not materialize 
1 = Materialize if the program is a bound service program. 
e Exported program procedure information Bit 2 
0 = Do not materialize 
1 = Materialize if the program is a bound service program. 
e Exported program data information Bit 3 
0 = Do not materialize 
1 = Materialize if the program is a bound service program. 
e Reserved (binary 0) Bits 4-7 
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Materialize Bound Program (MATBPGM) 


— Bound Modules materialization options Char(4) 
- General module information Bit 0 


QO = Do not materialize 
1 = Materialize 


- Reserved! Bit 1 
- Module string directory component Bit 2 
OQ = Do not materialize 
1 = Materialize 
- Reserved! Bits 3-10 
- Reserved (binary 0) Bits 11-17 
- Module copyright strings Bit 18 
0 = Do not materialize 
1 = Materialize 
- Reserved (binary 0) Bits 19-31 
— Bound Module materialization number UBin(4) 
— Reserved (binary 0) Char(4) 


Description of bound program materialization request template fields: Each of the reserved fields 
must be set to binary zeroes, or a template value invalid (hex 3801) exception will be signaled. 


Number of bytes provided 


This is the size in bytes of the materialization request template. If this size does not corre- 
spond to the actual number of bytes in the materialization request template, then a template 
value invalid (hex 3801) exception will be signaled. This does not include any storage for 
returned data. That storage is pointed to by the receiver values. 


Number of materialization requests 


The number of requests in the array of materialization requests is specified by this value. If 
this number is greater than the actual number of materialization requests provided, then a 
template value invalid (hex 3801) exception will be signaled. 


Materialization requests 
This is an array of materialization requests. A materialization request consists of one or 


more bits, and an optional module number specified to be materialized into the corre- 
sponding receiver. Each materialization request consists of the following fields. 


Receiver 
This is a pointer to a space which will hold the materialized data. The space 
pointed to must be aligned on a 16-byte boundary, and must be at least 8 bytes 
long. This is so that it can hold the bytes provided and bytes available field of 
the receiver. |f the space is not at least 8 bytes long a template value invalid 
(hex 3801) exception will be signaled. 


Bound Program materialization options : 
This bit mapped field specifies the parts of the bound program object to be mate- 


rialized. A materialization request need not specify any program materialization 
options. If no bits are set, a bit must be set in the bound module materialization 
options field, or a template value invalid (hex 3801) exception will be signaled. 
Mutiple options may be specified. When multiple options are specified, all of the 
requested data will be materialized into one receiver. The pieces requested on 
the materialization will be placed in the receiver in the order that the option bits 
are defined. For example, if all data is requested, the general bound program 
information will be the first item in the receiver and the exported program data 
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Materialize Bound Program (MATBPGM) 


information will be the last item. If options are also specified on the bound 
module materialization options field. the materialized data for those options will 


‘follow that data materialized for the bound program materialization options. 


The bound program materialization options are split into three distinct 
materialization bit sets. 


1. The general bound program materialization options contains bits that repre- 


sent data that can be materialized for either bound programs or bound 
service programs. 


2. The specific bound program materialization options contains bits that repre- 


sent data that can be materialized only for bound programs, and not for 
bound service programs. 


3. The specific bound service program materialization options contains bits that 


represent data that can be materialized only for bound service programs. 


If a bit is on to materialize information that is not contained in the type of bound 
program being materialized, then an indication that the information is not 
materializable will be provided in the receiver header. No exception, in this 
case, will be signaled. 


Each of the requested pieces will be placed on a 16-byte boundary within the 
receiver. 


The general bound program information field specifies that general information 
about the bound program object should be materialized. 


The program copyright strings field specifes that the collected program copyright 
strings of the constituent bound modules should be materialized. 


The bound service programs information field specifies that information about the 
service programs bound to the materialized bound program should be material- 
ized. These bound service programs are those that contain exports that resolve 
to imports in the materialized bound program. 


The bound modules information field specifies that information about the 
modules bound into the materialized bound program should be materialized. 


The bound program string directory component field specifies that the bound 


program string directory should be materialized. 


The bound program limits field specifies that the current sizes and maximum 
values of the bound program components should be materialized. 


The activation group data imports field specifies that information about those 
data imports resolving to weak activation data exports is be materialized. 


The activation group data exports field specifies that information about those 
data exports promoted to the activation group is to be materialized. 


The specific bound program information field specifies that information specific 
to a bound program, and not to a bound service program, should be material- 


ized. 


The signatures information field specifies that the bound program signatures 
should be materialized. 


The exported program procedure information field specifies that the exported 


procedures specified during program creation should be materialized. 


2 Referential extensions are data streams that are not included in the creation templates, but are pointed to by a space pointer 


Chapter 8. Program Management Instructions 8-6 


eee. pene ape 


i —— ——_ ——" —: —— 


Materialize Bound Program (MATBPGM) 


The exported program data information field specifies that the exported data 
specified during program creation instruction should be materialized. 


Bound Module Materialization Options 


This bit mapped field specifies the parts of the modules bound into the program 
that are to be materialized. A module materialization request need not specify 
any materialization options. If no bits are set, a bit must be set in the bound 
program materialization options field, or a template value invalid (nex 3801) 
exception will be signaled. Multiple options may be specified. When multiple 
options are specified, all of the requested data will be materialized into one 
receiver. The pieces requested on the module materialization will be placed in 
the receiver in the order that the option bits are defined. For example, if all data 
is requested, the general module information will be the first item in the receiver 
and the module string directory component will be the last item. If options are 
also specified on the bound program materialization options field, the material- 
ized data for those options will precede that data materialized for the bound 
module materialization options. 


In addition, each of the requested pieces will be placed on a 16 byte boundary 
within the receiver. 


The general module information field specifies that general information about the 
module object should be materialized. 


The module string directory component field specifies that the string directory of 
the associated module(s) should be materialized. 


The module copyright strings field specifies that the module copyright strings 
should be materialized. 


Bound Module Materialization Number 


lf at least one bit of the Bound Module Materialization Options field is on, then 
this is the number of the module to materialize, from 1 through the number of 
modules bound into the program; or 0, to materialize information about all 
modules bound into the program. lf this number is greater than the number of 
modules bound into the program, then a template value invalid (hex 3801) excep- 
tion will be signaled. 


The information that is materialized is specified in the bound module 
materialization options field. 


If no bits of the bound module materialization options field are on, then no 
module information is being materialized, and this field must be binary Qora 
template value invalid (hex 3801) exception will be signaled. 


Format of materialized data 


Format of Receiver 


« Number of bytes provided for materialization UBin(4) 
¢ Number of bytes available for materialization UBin(4) 
« Reserved (binary 0) Char(8) 


« Materialized data 


Bytes provided 


Char(*) 


This is the number of bytes the user is providing to hold the materialized data. It must be 
greater than or equal to eight. If it is equal to eight, then no data will actually be material- 
ized, and the number of bytes required to materialize the requested data will be placed in 
bytes available. lf the value provided is greater than eight, but less than the number of 

bytes required to hold the requested data, the data will be truncated and no exception will 
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be signaled. Note that a value greater than eight, but less than 16 will result in no data 
being materialized, since bytes 9-16 are reserved. 


If the receiver is smaller than the size indicated by bytes provided. and the materialized 
data is larger than the space provided in receiver, the space addressing (hex 0601) excep- 
tion will be signaled unless receiver is an automatically extendable space object. If receiver 
is an automatically extendable space object, the space will be extended, up to its maximum 
size. 


Bytes available 


If bytes provided is greater than eight, this contains the number of bytes that have been 
used for the materialization, including any reserved bytes or bytes used for padding. If 
bytes provided is equal to eight, this contains the total size of the receiver needed to hold 
the requested materialization. A value of zero is returned if there is no data to materialize. 


Materialized data 
For each bit on in the bound program materialization options and bound module 
materialization options, this will contain the associated data. Each entry will be preceded 
by a common header which identifies the type of data and the offset to the next entry. 
When multiple bits are on in the same request, the data is returned in the order defined by 
the bound program materialization options and the bound module materialization options. 


No exception is signaled when the size of the receiver, as specified by bytes provided is not 
large enough to hold data for all requested bound program materialization options and 
bound module materialization options. Instead, the data is truncated and bytes provided 
only reflects the actual amount of data returned. One of several conditions may arise, each 
with a different result. 


If the receiver is not large enough to hold the materialization header, no data is returned for 
that bound program materialization option or bound module materialization option. The 
offset to next entry field in the previous materialization header, if one exists, is set to 0, and 
the bytes available field is set to reflect the amount of data actually materialized for the 
bound program materialization options or bound module materialization options that have 
already been processed. Bytes available will be set to 8, or bytes provided ; whichever is 
less, if the receiver is not big enough to hold the first materialization header. 


If the receiver is big enough to hold the materialization header, but not big enough to hold 
all of the data requested by the bound program materialization option or bound module 
materialization option, the partial data flag will be set in the materialization header and as 
much data will be returned for which there is room. For data which consists of one contin- 
uous stream the receiver will be filled and bytes available will equal bytes provided. For 
data which consists of an option specific header followed by an array of homogenous ele- 
ments‘ data will be returned in such a way that no partial option specific header or array 
element will be returned. If there is not enough room to hold the entire option specific 
header, none of it will be returned. If there is room for the option specific header, but not 
all of the entries, only those entries that will fit will be returned. The number of entries in 
the option specific header will reflect the number of entries returned rather than the actual 
number of entires available in the module. Bytes availab/e will reflect the actual amount of 
data returned and may not equal bytes provided. Note that because many option specific 
headers and entries are larger than the common materialization header, there may be more 
than one option for which partial data is returned. 


3. The items that fall into this category are general bound program information, bound program limits, specific bound program 
information, specific bound service program information, generai module information, bound program string directory compo- 
nent, module string directory component and module copyright strings. 

4 The items which fail into this catagory are bound service programs information, bound modules information, signatures infor- 
mation, program copyright strings, exported program procedure information, activation group data imports, activation group 
data exports, and exported program data information. 
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Format of Common Materialization Header 


¢ Offset to next entry UBin(4) 
¢ Bound Program materialization identifier Char(4) a 
* Bound Module materialization identifier Char(4) 
* Bound Module materialization number identifier UBin(4) 
° Flags Char(4) 
— Entry presence Bit O 


0 = No data present for entry 
1 = Data present for entry 


Partial data Bit 1 


O = All data in materialization was returned 
1 = Partial data was returned because receiver was too small to hold all data for the 
requested option 


Valid Materialization data Bit 2 


0 = The data requested in this materialization request is never present for the type of bound 
program being materialized. 

1 = The data requested in this materialization request may be present for the type of bound 
program being materialized. 


— Reserved (binary 0) Bits 3-31 
e Reserved (binary 0) Char(12) 
Offset to next entry i | 
This contains the offset from the beginning of this entry to the beginning of the next entry. It J 


will contain zero if this is the last entry. 


Bound Program materialization identifier 


This indicates which portion of the bound program is contained in this entry. It is the bit 
which was on in bound program materialization options that resulted in this data being 
materialized. Either no bits, or a single bit of this field will be on. If no bits of this field are 
on, then the data contained in this entry is indicated by the bound module materialization 
identifier field. 


Bound Module materialization identifier 


This indicates which portion of the module, indicated by the bound module materialization 
number identifier field, is contained in this entry. It is the bit which was on in the bound 
module materialization options field that resulted in this data being materialized. Either a 
single bit or no bit of this field will be on. If no bit is on, then the data contained in this 
entry is indicated by the bound program materialization identifier field. If a bit is set on, 
then that type of information will be returned in the entry. 


Bound Module materialization number identifier 


Flags 


If a bit of the bound module materialization identifier field is on, then this is the number of 
the module for which information has been materialized in this entry, and this field will not 
be 0. 


If no bits of the bound module materialization identifier field are on, then this field will be O. 


This field specifies information about the item being materialized. 


The entry presence field specifies whether there is data available for the requested item. 
Some items may not be encapsulated into the object, so no data will be returned when their 
materialization is requested. 
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The partial data field specifies that only a portion of the data was returned because suffi- 
cient space was not present in the receiver to hold ail of the data for the requested 


materialization option. 


The valid materialization field specifies whether the requested information is valid to be 


materialized for the type of bound program that is being materialized. For example, specific 
bound program information is not valid for a bound service program. Even if data may be 
present for the type of bound program being materialized does not mean that it actually is. 


Refer to the entry present field to see if it is. 


Format of materialized general bound program information 


Length in bytes of materialization 
Reserved! 

Number of secondary associated spaces 
Activation group attributes 

— Target activation group 


O = Default activation group 

1 = Caller’s activation group 
2 = Named activation group 

3 = Unnamed activation group 
4-255 reserved 


— Reserved' 

Activation group name 

Reserved! 

Coded character set identifier 

Composite language version§ 

Composite version on which module creations occurred$ 
Composite machine version$ 

Creation target versions 

Version on which creation occurred‘ 

Bound program identifier 


O = reserved 

1 Bound Program 

2 = Bound Service Program 
3-255 = reserved 


Compression status 
— Executable portion 


- 0 = Executable portion is not compressed 


All versions are represented as 16 bit values mapped as foliows. 


Bits 0-3 
Bits 4-7 
Bits 8-11 
Bits 12-15 


UBin(4) 
Char(264) 
UBin(4) 
Char(4) 
Char(‘1) 


_ Char(3) 


Char(30) 
Char(14) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
UBin(2) 
Char(1) 


Char(‘1) 
Bit 0 


Reserved (binary 0) 
Version 
Release 


Modification 
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- 1 = Executable portion is compressed 


— Observable portion Bit 1 
- Q = Observable portion is not compressed 
- 1 = Observable portion is compressed 
— Reserved (binary 0) Bits 2-7 
e Reserved' Char(178) 


Length in bytes of materialization 


This is the number of bytes materialized. For the general bound program information this 
will always be a constant 512. 


Number of secondary associated spaces 


This is the number of secondary associated spaces currently associated with the object. 


Activation group attributes 
The activation group attributes specify characteristics of the activation group into which the 


program will be activated. 


Target activation group 
This is the target activation group value specified when the bound program or 


bound service program was created. 


Activation group name 
This is the activation group name specified when the bound program or bound service 


program was created. 


Coded character set identifier 
This is the CCSID value of the bound program or bound service program. 


Composite language version 


This is the earliest version of the operating system on which the languages used for the 
bound modules will allow the bound program object to be saved. This is a composite® of all 
of the language versions of the modules bound into this program. 


Composite version on which module creations occurred 


This is the earliest version of the operating system on which all of the modules bound into 
the program can be re-created. This is a composite’ of all of the version-on-which-module- 
creations-occurred versions of the modules bound into this program. 


Composite machine version 


This is the earliest version of the operating system on which the machine will allow the 
bound program to be saved. This is a composite® of all of the machine versions of the 
modules bound into this program. 


Creation target version 


This is the version of the operating system for which the bound program object was created. 


Version on which creation occurred 
This is the version of the operating system on which the bound program object was created. 


Bound program identifler 
This field identifies the type of bound program being materialized. 


8 A composite version is defined to be the latest version, in time, of all of the versions comprising the composite. Given back- 
level compatibility, this would be the earliest version of the operating system on which all of the comprising versions would be 
compatible. 
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Compression status 
This field identifies whether the executable or the observable portions of the bound program 


or bound service program are compressed. 


Format of materialized program copyright strings 


¢ Length in bytes of materialization Ubin(4) 
e Version of copyright creation extension Ubin(4) 
« Number of copyright statements in the pool Ubin(4) 
e Reserved Char(4) 
¢ Copyright string pool Char(*) 


Length in bytes of materialization 


This is the number of bytes materialized. 


Version of copyright creation extension 
This is the version of the copyrights when the module was created. 


Number of copyright strings in the pool. 
This is the number of copyright strings that follow. 


Copyright statement pool. 
This is the data for all of the copyright strings. Each copyright string consists of a 4 byte 


length followed by the text of the string. The length reflects the actual length of the copy- 
right string and does not include the length of the length field. All copyright strings along 
with their lengths are placed contiguously in the buffer with no intervening padding. 


Format of the materialized bound service programs information 


e Length in bytes of materialization UBin(4) 
e Number of service programs bound to this program UBin(4) 
e Reserved (binary 0) Char(8) 
e Array of bound service program records Char(*) 
— Bound service program ID Char(24) 
- Bound service program context object type Char(1) 
- Bound service program context object subtype Char(1) 
- Bound service program context name Char(10) 
- Bound service program object type Char(1) 
- Bound service program object subtype Char(1) 
- Bound service program name Char(10) 
— Referentially bound program signature Char(16) 
— Reserved (binary 0) Char(8) 


Length in bytes of materialization 


The number of bytes materialized. This will be 16 + (N * 48) where N is the number of 
bound servide programs — those programs that contain exports that resolve imports in the 
bound program. 


Number of service programs bound to this program 
This is the number of bound service programs bound to the bound program. 
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Array of bound service program records 


This array contains one record for each bound service program bound to the bound 
program. Each record contains the following information ) 


Bound service program context type 


This is the object type of the context with the given name. 


Bound service program context subtype 


This is the object subtype of the context with the given name. 


Bound service program context name 


This is the context specified during program creation where this bound service 
program was found when the bound program was created. This value could be 
set with all hex zeroes, in which case the name resolution list is used to locate 
the given bound service program. 


Bound service program type 


This is the object type of the program with the given name. 


Bound service program subtype 


This is the object subtype of the program with the given name. 


Bound service program name 


This is the name of the bound service program specified during program cre- 
ation. 


Bound service program signature 
This is the signature of the bound service program that was used to match 


against the current signature of the bound program. 


Format of the materialized bound modules information <, 
e Length in bytes of materialization UBin(4) J 
¢ Number of modules bound into this program UBin(4) 
e Reserved (binary 0) Char(8) 
e Array of bound module records Char(*) 
— Bound module ID Char(60) 
- Module qualifier Char(30) 
- Module name Char(30) 
— Reserved (binary 0) Char(20) 


Length in bytes of materialization 


The number of bytes materialized. This will be 16 + (N * 80) where N is the number of 
modules bound into the bound program. 


Number of modules bound into this program 


This is the number of modules bound into the bound program. 


Array of bound module records 


This array contains one record for each module bound into the bound program. Each 
record contains the following information 


Module qualifier 
This is the qualifier specified during program creation where this module was 


found when the bound program was created. The module qualifier is used to 
differentiate between two different modules of the same name. This usually con- 3 
tains a context name. 
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Module name 
This is the name of the module. 


e Length in bytes of materialization 


e Reserved (binary 0) 


String Pool 

— Length of the string 
— CCSID of the string 
— String 


Length in bytes of materialization 


The number of bytes materialized. This will be 16 + the length of the string pool. 


String Pool 


A memory area containing the strings defined for this program. It can be of any length 


UBin(4) 
Char(12) 
Char(*) 
UBin(4) 
UBin(2) 
Char(*) 


addressable by a UBin(4). It contains a series of strings and lengths. String IDs specified in 


other materialized components can be used as indexes into this string pool. 


Length of string 
The length of the next string. This field contains the length of the string only, and does not 


include the length of the either the length or the CCSID field. The length field of a string is 


not subject to alignment considerations. 


CCSID of string 
The character code set identifier of this string. This string is encoded in the given CCSID, 


which is the CCSID of the module object from which this string is originally declared. The 


CCSID field of a string is not subject to alignment considerations. 


String 


Character buffer which contains one string. Its length is defined by the length field. 


Format of the materialized bound program limits 


Length in bytes of materialization 

Reserved (binary 0) 

Current size of bound program 

Maximum number of associated spaces 

Current number of associated spaces 

Maximum number of modules bindable into program 
Current number of modules bound into program 
Maximum number of service programs bindable to program 
Current number of service programs bound to program 
Maximum size of bound program string directory 
Current size of bound program string directory 
Maximum size of bound program copyright strings 
Current size of bound program copyright strings 
Maximum number of auxiliary storage segments 
Current number of auxiliary storage segments 


Maximum number of static storage frames 
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¢ Current number of static storage frames UBin(4) 

¢ Maximum number of program procedure exports UBin(4) 

« Current number of program procedure exports UBin(4) J 
¢ Maximum number of program data exports UBin(4) 

¢ Current number of program data exports UBin(4) 

¢ Maximum number of signatures UBin(4) 

¢ Current number of signatures UBin(4) 

¢ Minimum amount of static storage required UBin(4) 

e Maximum amount of static storage required UBin(4) 

e Reserved (binary 0) Char(148) 


Length in bytes of materialization 


The number of bytes materialized. This will always be a constant 256. 


Current size of bound program 


This is the current size, in machine-dependent units, of the bound program being material- 
ized. 


Maximum _ number of associated spaces 
This is the maximum number of associated spaces allowed for the bound program being 


materialized. 


Current number of associated spaces 
This is the current number of associated spaces allocated to the bound program being 


materialized. 


Maximum _ number of modules bindable into program 


This is the maximum number of modules that can be bound into a bound program. 


Current number of modules bound into program 


This is the current number of modules bound into the bound program being materialized. 


Maximum number of service programs bindable to program 


This is the maximum number of bound service programs that can be bound to a bound 
program. These bound service programs contain exports to which imports from a bound 
program resolve. 


Current number of service programs bound to program 


This is the current number of bound service programs bound to the bound program being 
materialized. 


Maximum size of bound program string directory 


This is the maximum size, in bytes, of the bound program string directory. 


Current size of bound program string directory 
This is the current size, in bytes, of the bound program string directory. 


Maximum size of bound program copyright strings 
This is the maximum size, in bytes, of the bound program copyright strings. 


Current size of bound program copyright strings 
This is the current size, in bytes, of the bound program copyright strings. 


Maximum number of auxillary storage seqments 


This is the maximum number of auxiliary storage segments allowed for a bound program. 


Current number of auxillary storage seqments 


This is the current number of auxiliary storage segments in the bound program being mate- 
rialized. 


: yarn 
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Maximum number of static storage frames 
This is the maximum number of static storage frames allowed for a bound program. 


Current number of static storage frames 
This is the current number of static storage frames required by the bound program being 


materialized. 


Maximum number of procedure exports 
This is the maximum number of procedures that are allowed to be exported from a bound 


program. If the bound program being materialized is not a bound service program, then 
this value will be zero. 


Current number of procedure exports 
This is the current number of procedures exported from the bound program being material- 


ized. If the bound program being materialized is not a bound service program, then this 
value will be zero. 


Maximum number of data exports 
This is the maximum number of data items that are allowed to be exported from a bound 


program. If the bound program being materialized is not a bound service program, then 
this value will be zero. 


Current number of data exports 
This is the current number of data items exported from the bound program being material- 


ized. If the bound program being materialized is not a bound service program, then this 
value will be zero. 


Maximum number of signatures 
This is the maximum number of signatures allowed for a bound program. If the bound 


program being materialized is not a bound service program, then this value will be zero. 


Current number of signatures 
This is the current number of signatures contained in the bound program being material- 


ized. If the bound program being materialized is not a bound service program, then this 
value will be Zero. 


Minimum amount of static storage required. 


This is the smallest amount of static storage that is required for the bound program or 
service program. This measure is in bytes. The actual amount of static storage that is 
used may be anywhere between the minimum and the maximum amounts of required static 
storage, inclusive. 


Maximum amount of static storage required. 
This is the largest amount of static storage that may be required for the bound program or 


service program. This measure is in bytes. The actual amount of static storage that is 
used may be anywhere between the minimum and the maximum amounts of required static 
storage, inclusive. 


Format of the materialized activation group data imports 


e Length in bytes of materialization UBin(4) 
¢ Number of activation group data imports UBin(4) 
e Reserved (binary 0) Char(8) 
e Array of activation group data imports Char(*) 
— String ID UBin(4) 
— Reserved (binary 0) Char(12) 
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Length in bytes of materialization 


The number of bytes materialized. This will be (N+ ‘1)"16, where N is the number of acti- 
vation group data imports contained in the bound program or bound service program. J 


Number of activation group data imports 


The number of activation group data imports contained in the bound program or bound 
service program. 


Array of activation group data imports 


This array contains one record for each data item contained in the program or bound 
service program. Each record contains the following information: 


String ID 
This is the identification used to extract the name of this data item from the 


program string directory. 


Format of the materialized activation group data exports 


¢ Length in bytes of materialization UBin(4) 
e Number of activation group data exports UBin(4) 
e Reserved (binary 0) Char(8) 
e Array of activation group data exports Char(*) 
— String ID UBin(4) 
— Strength of data item Char(1‘) 
- Q = Reserved 
- 1 = Export Strongly 


- 2 = Export Weakly 
- 3-255 = Reserved 


re 


— Reserved (binary 0) Char(3) 
— Length of data item UBin(4) 
— Reserved (binary 0) Char(4) 


Length in bytes of materialization 


The number of bytes materialized. This will be (N+1)*16, where N is the number of acti- 
vation group data exports contained in the bound program or bound service program. 


Number of activation group data exports 


The number of activation group data exports contained in the bound program or bound 
service program. 


Array of activation group data exports 
This array contains one record for each data item contained in the program or bound 


service program. Each record contains the following information: 

String ID 
This is the identification used to extract the name of this data item from the 
program string directory. 

Strength of data item 
This field indicates whether the activation group export is exported strongly or 
weakly. 


Length of data item. 
The size in bytes of the activation group export. 
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Format of the materialized specific bound program information: Specific bound program information 
can only be materialized for bound programs, and not for bound service programs. 


¢ Length in bytes of materialization UBin(4) 
« Reserved (binary 0) Char(12) 
e Program entry procedure information Char(16) 
— Module number containing program entry procedure UBin(4) 
— Program entry procedure string [D UBin(4) 
— Minimum parameters UBin(2) 
— Maximum parameters UBin(2) 
— Reserved (binary 0) Char(4) 
e Reserved (binary 0) Char(32) 


Length in bytes of materialization 


The number of bytes materialized. This will always be a constant 64. 


Module number containing program entry procedure 


This is the number, in the bound modules information, of the module which contains the 
program entry procedure for this bound program. 


Program entry procedure string ID 


This is the string ID for the name of this program entry procedure. 


Minimum parameters 
This is the minimum number of parameters that the program entry procedure can accept. 


Maximum parameters 
This is the maximum number of parameters that the program entry procedure can accept. 


Format of the materialized signatures information: Signatures information can only be materialized for 
bound service programs, and not for bound programs. 


¢ Length in bytes of materialization UBin(4) 
e Number of signatures contained in the program UBin(4) 
e Reserved (binary 0) Char(8) 
¢ Array of signatures Char(*) 
— Signature Char(16) 


Length in bytes of materialization 


The number of bytes materialized. This will be (N+1)*16, where N is the number of signa- 
tures contained in the program. 


Number of signatures contained in the program 


This is the number of signatures contained in the program. 


Array of signatures 
This array contains one record for each signature contained in the program. Each record 


contains the following information. The first record contains the current signature. 


Signature 
A signature of the service program. 
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Format of the materialized exported program procedure information: Exported program procedure 
information can only be materialized for bound service programs, and not for bound programs. 


e Length in bytes of materialization UBin(4) 2 
e Number of exported procedures UBin(4) 
e Reserved (binary 0) Char(8) 
e Array of program exports Char(*) 
— $tring |D for procedure export UBin(4) 
— Export number UBin(4) 
— Reserved (binary 0) Char(8) 


Length in bytes of materialization 


The number of bytes materialized. This will be (N+ 1)*16, where N is the number of 
exported procedures. 


Number of exported procedures 
This is the number of procedures exported from the service program. 


Array of program exports 
This array contains one record for each procedure exported from the service program. 


Each record contains the following information: 


String ID for procedure export 
This is the identification used to extract the name of this exported procedure 


from the program string directory. 


Export number j 
This is the number of this exported procedure. J 


Format of the materialized exported program data information: Exported program data information 
can only be materialized for bound service programs, and not for bound programs. 


¢« Length in bytes of materialization UBin(4) 
« Number of exported data items UBin(4) 
e Reserved (binary 0) Char(8) 
e Array of data exports Char(*) 
— String ID for data export UBin(4) 
— Export number UBin(4) 
— Reserved (binary 0) Char(8) 


Length in bytes of materialization 


The number of bytes materialized. This will be (N+1)*16, where N is the number of 
exported data items. 


Number of exported data items 
This is the number of data items exported from the service program. 


Array of data exports 
This array contains one record for each data item exported from the service program. Each 


record contains the following information: 


String |D for data export 
This is the identification used to extract the name of this exported data item from J 


the program string directory. 


Export number 
This is the number of this exported data item. 
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Format of materialized general module information 


Length in bytes of materialization 


This is the number of bytes materialized. For the general module information this will 
always be a constant 512. 


Coded character set identifier 
The CCSID defines the code page of the symbols in the string directory. 


Language version 
This is the earliest version of the operating system on which language used will allow the 


module object to be saved. 


Creation target version 
This is the version of the operating system for which the module object was created. 


Version on which creation occurred 
This is the version of the operating system that was running on the system where the 
module object was created. 


| 

| © Length in bytes of materialization UBin(4) 
CC | © Reserved . Char(12) 

| © Reserved' Char(276) 

| © Coded character set identifier UBin(2) 

| © Reserved Char(10) 

| ¢ Creation target version’ Char(2) 

| © Language version’ Char(2) 

| © Version on which creation occurred Char(2) 

| © VLIC versions Char(2) 

| ¢ Reserved Char(16) 

| ¢« Number of secondary associated spaces UBin(4) 

| © Reserved Char(16) 

| © Reserved' Char(2) 

| ¢ Reserved Char(2) 

| © Compiler name Char(20) 

| © Program entry procedure Char(16) 

| Program entry procedure attributes | Char(4) 

| Program entry procedure exists Bit O 
= | 0 = Program entry procedure does not exist in this module 

| 1 = Program entry procedure exists in this module 

| Reserved (0) Bits 1-31 

| Program entry procedure dictionary id UBin(4) 

| Program entry procedure string id UBin(4) 

| Program entry procedure minimum parms UBin(2) 

| Program entry procedure maximum parms UBin(2) 

| © Reserved Char(124) 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 


c 
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Earliest version 
This is the earliest version of the operating system on which the machine will allow the 


module object to be saved. 


Number of secondary associated spaces 


This is the number of secondary associated space segments currently associated with the 
object. 


Compiler name 
This identifies the compiler which translated the user’s source language. 


Program entry procedure 
This identifies the program entry procedure if one is present in the module. 


Program entry procedure attributes 


This bit mapped field identifies attributes of the program entry procedure. 


The program entry procedure existence field specifies whether a program entry 
procedure is present in the module being materialized. 


Dictionary id of the procedure 


The dictionary id is used as a handle to uniquely identify the procedure. 


String id of the procedure name 
The string id may be used to extract the character string which is the procedure 


name from the string pool. 


Program entry procedure minimum parms 


This is the minimum number of parameters allowed by the program entry proce- 
dure. 


Program entry procedure maximum parms 


This is the maximum number of parameters allowed by the program entry proce- 
dure. 


Format of the materialized module string directory component 


e Length in bytes of materialization UBin(4) 

e Reserved (binary 0) Char(12) 

e String Pool Char(*) 
— Length of the string UBin(4) 
— String Char(*) 


Length in bytes of materialization 
The number of bytes materialized. This will be 16 + the length of the string pool. 


String Pool 
A memory area containing the strings defined for this module. It can be of any length 


addressable by a UBin(4). It contains a series of strings and lengths. String IDs specified in 
other materialized components can be used as indexes into this string pool. 


Length of string 
The length of the next string. This field contains the length of the string only, and does not 


include the length of the length field, itself. The length field of a string is not subject to 
alignment considerations. 


String 
Character buffer which contains one string. Its length is defined by the length field. 


Format of the materialized module copyright strings: The format of the materialized module copyright 
strings is the same as for the materialized program copyright strings. 
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Template Value Invalid exception reason codes: This instruction supports setting of the optional 
reason code field in the exception data which can be retrieved when the template value invalid excep- 
tion is signaled. When the first byte of the reason code is not zero, the exception is being signaled 


because one of the materialization receivers is not valid. 


00 Bound Program Materialization Template (pointed to by operand 1 of this instruction) 


01 Size of template is not sufficient to hold number of requests specified. 


On nth materialization request is not valid. 
01 The receiver is not aligned on a 16 byte boundary. 


02 The materialization request bytes provided is less than 8. 


03 The materialization request contains no materialization options or invalid materialization 


options. 


If the /ength of field data is 8, then no materialization options were specified and the offset in 

field in bits data will be 0. Otherwise, an invalid option was specified and the provided offset 

to field in bytes and offset in field in bits data will identify the invalid materialization option. 
04 The materialization request contains a module materialization number that is greater than 


the number of modules bound into the program. 


O05 The materialization request contains a non-zero module materialization number, but no 


module materialization options. 


O06 The materialization request contains a non-zero reserved field. 


Authorization Required 
e Retrieve 
— OQOperand 2 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 
— OQOperand 2 


— Contexts referenced for address resolution 


Exceptions 


Exception 

06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation 


0A Authorization 


01 unauthorized for operation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Operands 
1 2 Other 


X X 
X X 
X X 
X X 
X X 
X 

X X X 

X 

X X X 


Chapter 8. Program Management Instructions 


8-22 


Materialize Bound Program (MATBPGM) 


Exception 


iA 


iC 


20 


22 


24 


2E 


36 


38 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

04 object inelligible 

07 authority verification terminated due to destroyed object 
0A program object inelligible 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 
02 template size invalid 


03 materialization length exception 


Operands 
1 2 
X 
X X 
X X 
X X 
X X 
X 
X X 
X X 
X 
X 
X 


Other 


~< 
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Materialize Program (MATPG) 


Op Code (Hex) Operand 1 Operand 2 
0232 Attribute receiver Program 


Operand 1: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATPG ( 
receiver : space pointer; 


var program : system pointer 


) 


Description: The program identified by operand 2 is materialized into the template identified by 
operand 1. 


Operand 2 is a system pointer that identifies the program to be materialized. The values in the 
materialization relate to the current attributes of the materialized program. 


The template identified by operand 1 must be 16-byte aligned. 


The first 4 bytes of the materialization template identify the total number of bytes provided in the tem- 
plate. This value is supplied as input to the instruction and is not modified. A value of less than 8 
causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization template are modified by the instruction to contain a value 
identifying the template size required to provide for the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified by the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
the materialization. 


The following attributes apply to the materialization of a program: 
¢« The existence attribute indicates whether the program is femporary or permanent. 


e The observation attribute field specifies the template components of the programs that currently 
can be materialized. 


e If the program has an associated space, then the space attribute is set to indicate either fixed- or 
variable-length; the initial value for the space is returned in the initial value of space field, and the 
size of space field is set to the current size value of the space. If the program has no associated 
space, the size of space field is set to a zero value, and the space attribute and initial value of 
space field values are meaningless. 


e (f the program is addressed by a context, then the context addressability attribute is set to indicate 
this, and a system pointer to the addressing context is returned in the context field. If the program 
is not addressed by a context, then the context addressability attribute is set to indicate this, and 
binary O’s are returned in the context field. 


e If the program is a member of an access group, then the access group attribute is set to indicate 
this, and a system pointer to the access group is returned in the access group field. If the program 
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is not a member of an access group, then the access group attribute is set to indicate this, and 
binary O’s are returned in the access group field. 


e The performance class field is set to reflect the performance class information associated with the 
program. 


e The user exit attribute defines if the referenced program is allowed to be used as a user exit 
program. 


Components of the program template may not be present if they have been removed by the Delete 
Program Observability instruction. Also, a template component will not be available if the program 
was Created with its corresponding observation attribute in the Create Program template set to binary 
0. If a template component cannot be materialized, 0’s are placed in the fields of the program tem- 
plate that describe the size and offsets to that component. 


The offset to the OMT component field specifies the location of the OMT component in the materialized 
program template. The OMT consists of a variable-length vector of 6-byte entries. The number of 
entries is identical to the number of ODV entries because there is one OMT entry for each ODV entry. 
The OMT entries correspond one for one with the ODV entries; each OMT entry gives a location 
mapping for the object defined by its associated ODV entry. 


The following describes the formats for an OMT entry: 
¢ OMT entry Char(6) 
— Addressability type Char(1) 
Hex 00= Base addressability is from the start of the static storage 
Hex 01= Base addressability is from the start of the automatic storage area 


Hex 02= Base addressability is from the start of the storage area addressed by a space 
pointer 


Hex 03= Base addressability is from the start of the storage area of a parameter 


Hex 04= Base addressability is from the start of the storage area addressed by the space 
pointer found in the process communication object attribute of the process executing 
the program 


Hex FF = Base addressability not provided. The object is contained in machine storage areas 
to which addressability cannot be given, or a parameter has addressability to an object 
that is in the storage of another program 


— Offset from base Char(3) 


For types hex 00, hex 01, hex 02, hex 03, and hex 04, this is a 3-byte logical binary value 
representing the offset to the object from the base addressability. For type and hex FF, the 
value is binary 0. 


— Base addressability Char(2) 


For types hex 02 and hex 03, this is a 2-byte binary field containing the number of the OMT 
entry for the space pointer or a parameter that provides base addressability for this object. 
For types hex 00, hex 01, hex 04 and hex FF, the value is binary 0. 


Authorization Required 
e Retrieve 
— Operand 2 


— Contexts referenced for address resolution 
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Lock Enforcement 
¢ Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK XK 
~ KK KK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage state X X X 


»~< 


05 authority verification terminated due to damaged object 


44 partial system object damage X X X 


1A Lock state 


01 invalid lock state D< 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check Xx 


22 Object access 
01 object not found | X X 


x< 
x 


02 object destroyed 
03 object suspended X X 
07 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 


01 pointer does not exist Xx X 


x 


02 pointer type invalid X 


03 pointer addressing invalid object X 


2E Resource control limit 


01 user profile storage limit exceeded X 
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Exception 
36 Space management 


01 space extension/truncation 


38 Template specification 


03 materialization length exception 


Materialize Program (MATPG) 


Operands 

1 2 Other 
X 

X 
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Chapter 9. Program Execution Instructions 


This chapter describes the instructions used for program execution control. These instructions are in 
alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 


Activate Program (ACTPG) .... 2... 0.0. ee ee 9-3 
Cail Exteriar (CALI): <<) aoe ae yd or ase or On Be Se be Bae aot a BS be be CRS 9-5 
Call internal (GALI) cc. 2. B.G, Bete be arta aca ce Mots ed Rok Goes i See Bid ty, WS & eet he 9-9 
Clear Invocation Exit (CLRIEXIT) .........0.... 0.00.00 000000 ee eee 9-14 
Deactivate Program (DEACTPG) ........... 000000000. ee ee ee 9-12 
EQGEIND)! (cn. 4.x oc wane Bee ht ee le a See Se ee oe ee me Be ee 9-14 
Materialize Activation Attributes (MATACTAT) ...........0. 0... 00 2 ee eee eee ees 9-15 
Materialize Activation Group Attributes (MATAGPAT) ............0 0... 0.02 eee eee 9-19 
Modify Automatic Storage Allocation (MODASA) ............. 0.000. eee ees 9-23 
FREtUP EXIGrNal(R IA) 3-2 6- aso-u & ed Bash we God Aba gak HA OL ee ee ee ace betes 9-25 
Set Argument List Length (SETALLEN) ........ 20... 0.0.00 0 cee es 9-27 
SEL INVOCALION- EXIC(SEMEAIN):  .:A0a5:3 26-0) 6 ee Kh eae a oe a ee ee ES A we 9-29 
Store Parameter List Length (STPLLEN) ....................004 Hace Se sh Gabe ee he ee 9-31 
TEANSTO-CORIFOIIXGEE): cd cdg eG Gs aS Ae ae a A, Goth a EA Se th GH Dl Ee | 9-33 
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Op Code (Hex) Operand 1 Operand 2 
0212 Program or static Program 
storage frame 


Operand ?: Space pointer data object, system pointer. 


Operand 2: System pointer. 


ILE access 


ACTPG ( 

var activation : system pointer; OR 
space pointer; 

var program : system pointer 


) 


Activate Program (ACTPG) 


Warning: The following information is subject to change from release to release. Use it with caution 


and be prepared to adjust for changes with each new release. 


Description: This instruction creates an activation entry for the program specified by operand 2, if it 
uses Static storage. If the program specified is a bound program, an invalid operation for program (hex 
2C15) exception is signaled. No operation is performed for a program which does not require static 


storage. 


Operand 1 receives either a space pointer or system pointer as follows: 


If an activation entry is created or an activation entry exists for the program within the target acti- 
vation group, then a space pointer to the static storage frame is returned. The static storage frame 
is allocated and initialized according to specifications within the program. The static storage frame 
is 16-byte aligned and begins with a 64-byte header. The header is not initialized and it is not used 
by the machine. The header is provided for compatibility with prior machine implementations. 


e If the program does not use static storage (hence, no activation entry is created) a copy of the 


program pointer in operand 2 is returned. 


If an attempt is made to activate an already active program then 


e the activation mark of the activation entry is unchanged, and 


e the static storage frame is reinitialized 


A space pointer machine object may not be specified for operand 1. 


Authorization Required 
¢ Operational 
— Program referenced by operand 2 
¢« Retrieve 


— Contexts referenced for address resolution 
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Lock Enforcement 
« Materialize 


— Contexts referenced for address resolution 


Exceptions 


Exception 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 
06 optimized addressability invalid 


OA Authorization 


01 unauthorized for operation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1A Lock state 


01 invalid lock state 


1C Machine-dependent exception 


03 machine storage limit exceeded 


20 Machine support 
02 machine check 


03 function check 


22 Object access 
01 object not found 
02 object destroyed 
03 object suspended 
07 authority verification terminated due to destroyed object 


08 object compressed 


24 Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


2C Program execution 


15 invalid operation for program 


2E Resource control limit 


01 user profile storage limit exceeded 


36 Space management 


Activate Program (ACTPG) 


Operands 
1 2 Other 


X X 
X X 
X X 
X X 
X 
X X X 
X 
X Xx X 
X 
X 
X 
X 
X X 
X X 
X X 
X 
X 
X 
X X 
X 
X 
X 
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Operands 
Exception 1 2 Other 
( 01 space extension/truncation X 
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Call External (CALLX) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 J 
0283 Program to be Argument list Return list 

called or Call tem- 

plate 


Operand 7: System pointer or Space pointer data object. 
Operand 2: Operand list or null. 
Operand 3: Instruction definition list or null. 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: The instruction preserves the calling invocation and passes control to either the program 
entry procedure of a bound program or the external entry point of a non-bound program. If operand 1 

specifies a bound program which does not contain a program entry procedure, an invalid operation for 
program (hex 2C15) exception is signaled. 


Operand 1 may be specified as a system pointer which directly addresses the program that is to 
receive control or as a space pointer to a call template which identifies the program to receive control. 
Specifying a template allows for additional controls over how the specified program is to be invoked. 
The format of the call template is the following: ) 


¢ Call options Char(4) i 
— Suppress adopted user profiles Bit 0 J 
0 = No 
1 = Yes 
— Reserved (binary 0) Bits 1-30 
— Force process state to user state for call Bit 31 
0 = No 
1 = Yes 
e Reserved (binary 0) Char(12) 
¢« Program to be called System pointer 


The suppress adopted user profiles call option specifies whether or not the program adopted and prop- 
agated user profiles which may be serving as sources of authority to the process are to be suppressed 
from supplying authority to the new invocation. Specifying yes causes the propagation of adopted user 
profiles to be stopped as of the calling invocation, thereby, not allowing the called invocation to benefit 
from their authority. Specifying no allows the normal propagation of adopted and propagated user 
profiles to occur. The called program may adopt its owning user profile, if necessary, to supplement 
the authority available to its invocation. 


The force process state to user state option specifies whether or not the call changes the state of the 
process to user state. 
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Common Program Cail Processing: The details of processing differ for non-bound and bound pro- 
grams. The following outlines the common steps. 


1. A check is made to determine if the caller has authority to invoke the program and that the object 
is indeed a program object. The specified program must be either a bound program that contains 
a program entry procedure or a non-bound program. 


2. The activation group in which the program is to be run is located or created if it doesn’t exist. The 
activation group supplies the storage resources required for program execution: static, automatic, 
and heap storage. 


3. If the program requires an activation entry and it is not already active within the appropriate acti- 
vation group, it is activated. Bound programs always require an activation; non-bound programs 
require an activation only if they use static storage. The invocation count of a newly created acti- 
vation is set to 1 while the invocation count of an existing activation is incremented by 1. 


4. The invocation created for the target program has the following attributes (as would be reported 
via the Materialize Invocation Attributes instruction.) 


e the invocation mark is one higher than the current mark count value maintained for the 
process. If the program was activated as a result of the call then its invocation mark will equal 
the activation mark, otherwise the invocation mark is larger than the activation mark. 


Note: The so-called mark counts are generated from a counter maintained for the process. 
Each time a mark is required the counter is incremented. The mark counts thus form a 
non-decreasing sequence of unique identifiers which can be used to distinguish the time 
ordering of activations, invocations, and activation groups. 


e the invocation number is one greater than the invocation number of the calling invocation. This 
is merely a measure of the depth of the call-stack. 


e the invocation type is hex 01 to indicate a CALLPGM or CALLX invocation. 
e the invocation number is the same as the invocation number of the transferring invocation. 
e the invocation type is hex Q2 to indicate a XCTL type of invocation. 

5. The automatic storage frame (ASF), if required, is allocated on a 16-byte boundary. 

6. Control is transferred to the program entry procedure (or external entry point) of the program. 


7. Normal flow-of-control resumes at the instruction following the program call instruction after a 
return from the program. 


8. Normal flow-of-control resume at the instruction following the caller of the program issuing the 
XCTL instruction. 


The details of locating the target activation group and activating the program differ depending upon the 
model of the program. 


Bound Program: A bound program is activated and run in an activation group specified by program 
attributes. There are two logical steps involved: 

e locate the existing, or create a new activation group for the program 

¢ locate an existing, or create a new activation entry for the program within the activation group. 
After locating the activation entry for the program, control is passed to the program entry procedure for 


the program. If required, the activation group is destroyed when the invocation for the program entry 
procedure is destroyed. 
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Non-bound Program: The automatic storage frame begins with a 64 byte header. if the program 

defines no automatic data items the frame consists solely of the 64-byte header, otherwise the auto- 

matic storage items are located immediately following the header. In prior releases of the machine, J 
this header contained invocation information which is now available via the Materialize Invocation 

Attributes (MATINVAT) instruction. This header is not initialized and the contents of the header are not 

used by the machine. (The space is allocated merely to provide for compatibility with prior implemen- 

tations of the machine.) The update PASA stack program attribute, supported in prior implementations 

of the machine, is no longer meaningful and is ignored, if specified as an attribute of the program. 


Following the allocation and initialization of the invocation entry, control is passed to the invoked 
program. 


Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation entry 
to be called. If operand 2 is null, no arguments are passed by the instruction. A parameter list length 
(hex 0802) exception is signaled if the number of arguments passed does not correspond to the 
number required by the parameter list of the target program. 


Operand 3 specifies an IDL (instruction definition list) that identifies the instruction number(s) of alter- 
nate return points within the calling invocation. A Return External instruction in an invocation imme- 
diately subordinate to the calling invocation can indirectly reference a specific entry in the IDL to cause 
a return of control to the instruction associated with the referenced IDL entry. If operand 3 is null, then 
the calling invocation has no alternate return points associated with the call. If operand 3 is not null 
and operand 1 specifies a bound program, an invalid operation for program (hex 2C15) exception is 
signaled. 


Authorization Required 
« Operational 
— Program referenced by operand 1 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialize 


— Contexts referenced for address resolution 


Exceptions 


Operands 
Exception 1 2 3 Other 


06 Addressing 


01 space addressing violation 


X 
02 boundary alignment X 
03 range X 

X 


06 optimized addressability invalid 


08 Argument/parameter 
01 parameter reference violation X 


02 parameter list length violation X 


0A Authorization 


01 unauthorized for operation X 
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Exception 


10 


1A 


1c 


20 


22 


24 


2C 


2E 


36 


38 


Damage encountered 


04 system object damage state 


05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 
01 object not found 
02 object destroyed 


03 object suspended 


07 authority verification terminated due to destroyed object 


08 object compressed — 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Program execution 

15 invalid operation for program 
1D automatic storage overflow 

1E activation access violation 

1F program signature violation 

20 static storage overflow 

21 program import invalid 

22 data reference invalid 

23 imported object invalid 

24 activation group export conflict 


25 import not found 


Resource contro! limit 


01 user profile storage limit exceeded 


Space management 
01 space extension/truncation 
Template specification 


01 template value invalid 


Call Internal (CALLI) 


Operands 
1 2 3 Other 


X 
X 
X 
X 

X 

X 

X 
X 
X 

X 

X 

X 

X X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 

X 
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Call Internal (CALLI) 


Call Internal (CALLI) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 | 
0293 Internal entry Argument list Return target 
point 


Operand ?: Internal entry point. 
Operand 2: Operand list or null. 
Operand 3: Instruction pointer. 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: The internal entry point specified by operand 1 is located in the same invocation from 
which the Call Internal instruction is executed. A subinvocation is defined and execution control is 
transferred to the first instruction associated with the internal entry point. The instruction does not 
Cause a new invocation to be established. Therefore, there is no allocation of objects and instructions 
in the subinvocation have access to all invocation objects. 


Operand 2 specifies an operand list that identifies the arguments to be passed to the subinvocation. lf 

operand 2 is null, no arguments are passed. After an argument has been passed on a Call Internal 

instruction, the corresponding parameter may be referenced. This causes an indirect reference to the 

storage area located by the argument. This mapping exists until the parameter is assigned a new 

mapping based on a subsequent Call Internal instruction. A reference to an internal parameter before 

its being assigned an argument mapping causes a parameter reference violation (hex 0801) exception 4 
to be signaled. S) 


Operand 3 specifies an instruction pointer that identifies the pointer into which the machine places 
addressability to the instruction immediately following the Call Internal instruction. A branch instruc- 
tion in the called subinvocation can directly reference this instruction pointer to cause control to be 
passed back to the instruction immediately following the Call Internal instruction. 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 space addressing violation Xx 

02 boundary alignment X 

03 range X 

06 optimized addressability invalid X 
08 Argument/parameter 

01 parameter reference violation X 
10 Damage encountered 

04 system object damage state X X X X 

44 partial system object damage X X X X 
1C Machine-dependent exception 

03 machine storage limit exceeded X 
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Exception 


20 


22 


24 


2E 


36 


Machine support 
02 machine check 


03 function check 


Object access 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control /imit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Clear Invocation Exit (CLRIEXIT) 


Operands 
1 2 3 Other 


X 
X 
X 
X 
X 
X 
X 
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Deactivate Program (DEACTPG) 


Clear Invocation Exit (CLRIEXIT) 


Op Code (Hex) ; J 


0250 


Description: The instruction removes the invocation exit program for the requesting invocation. No 
exception is signaled if an invocation exit program is not specified for the current invocation. Also, an 
implicit clear of the invocation exit occurs when the invocation exit program is given control, or the 
program which set the invocation exit completes execution. 


Exceptions 
Exception Other 
10 Damage encountered 
04 System object damage state X 
44 Partial system object damage X 
1c Machine-dependent exception 
03 Machine storage limit exceeded xX 
20 Machine support 
02 Machine check X 
03 Function check X 
22 Object access t 
08 object compressed X ; ; 
2E Resource control limit 
01 user profile storage limit exceeded X 
36 Space management 
01 space extension/truncation X 
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Deactivate Program (DEACTPG) 


Deactivate Program (DEACTPG) 


Op Code (Hex) Operand 1 
0225 Program 


Operand 7: System pointer or null. 


ILE access 


DEACTPG ( 
var program : system pointer or 


null operand 


Description: This instruction, provided that certain conditions are met, deactivates a non-bound 
program. Subsequent invocations of the program within the same activation group will cause a new 
activation to be created. 


Operand 1 specifies program activation entry which is to be deactivated, if permitted. The activation 
entry is inferred by one of two means: 
1. operand 7 is null — the target activation entry is that associated with the current invocation 
2. operand 7 is not null — the target activation entry associated with the program system pointer is 
selected from one of the two default activation groups 


The target activation entry is deactivated if permitted. An activation in use by invocation (hex 2CQ5) 
exception is signaled if the deactivation is not permitted. If the target activation entry does not exist, 
then no operation is performed. If the program specified is a bound program, an invalid operation for 
program (hex 2C15) exception is signaled. 


In general, only those activations with a zero invocation count can be deactivated. The following two 
exceptions apply: 


1. A program can deactivate itself if it is the only invocation of that program in the process (its invo- 
cation count must be 1.) 


2. An invocation exit program can deactivate the program on whose behalf it is running provided that 
the invocation count of that program is no more than 1. 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 


Exceptions invalid operation for program 


Operand 
Exception 1 Other 


06 Addressing 
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Exception 


08 


0A 


10 


20 


22 


24 


2C 


2E 


32 


36 


01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Program execution 
05 activation in use by invocation 


15 invalid operation for program 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


End (END) 


Operand 
1 Other 
X 
X 
X 
X 
X 
X 
X X 
X 
X X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
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Materialize Activation Attributes (MATACTAT) 


End (END) 


Op Code (Hex) 
0260 


Description: The instruction delimits the end of a program’s instruction stream. When this instruction 
is encountered in execution, it causes a return to the preceding invocation (if present) or causes termi- 
nation of the process phase if the instruction is executed in the highest-level invocation for a process. 
The End instruction delineates the end of the instruction stream. When it is encountered in execution, 
the instruction functions as a Return External instruction with a null operand. Refer to the Return 
External instruction for a description of that instruction. 


Exceptions 
Exception Other 
10 Damage encountered 

04 system object damage state X 

44 partial system object damage X 
1¢ Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check X 

03 function check X 
22 Object access 

08 object compressed X 
2E Resource control limit 

01 user profile storage limit exceeded X 
36 Space management 

01 space extension/truncation Xx 
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Materialize Activation Attributes (MATACTAT) 


Materialize Activation Attributes (MATACTAT) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0213 Receiver Activation mark Attribute selection 


Operand 7: Space pointer 
Operand 2: Binary(4) scalar 


Operand 3: Character(1) scalar (fixed length) 


ILE access 
MATACTAT ( 
receiver : space pointer; 
var activation mark : unsigned binary; 


var attribute selection : aggregate 


) 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: This instruction will materialize the information selected by operand 3 for the program 
activation specified by operand 2 and return the information in the template supplied by operand 1. 


The operand 3 selection operand is provided to deal with the variable-length nature of some of the 
returned information. All “length-of-list” type information can be gathered by selecting the first option 
described below. 
Operand 3 can have the following values: 

e hex 00 — basic activation attributes 


e hex 01 — static storage frame list 
Any value for operand 3 other than those listed will cause a scalar value invalid (hex 3203) exception. 


Operand 2 supplies the activation mark of the activation for which information is to be returned. The 
activation mark uniquely identifies an activation within a process. A value of zero is interpreted to be 
a request for information about the activation of the invoking program. 


The materialization template identified by operand 1 must be 16-byte aligned in the space. This 
materialization template has the following format: 


¢ Template size specification Char(8) 
Number of bytes provided for materialization Bin{4) 
— Number of bytes available for materialization Bin(4) 

— Reserved (binary 0) Char(8) 

¢ Returned information Char(*) 


The number of bytes provided indicates the number of bytes provided for returned information by the 
user of the instruction. In all cases if the number of bytes provided is less than 8, then a 
materialization length (hex 3803) exception will be signaled. 
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Materialize Activation Attributes (MATACTAT) 


The number of bytes available is set by the instruction to indicate the actual number of bytes available 
to be returned. In no case does the instruction return more bytes of information than those available. 


The format of returned information is described in the following paragraphs. 


Basic Activation Attributes: The following information is returned when operand 3 is hex QO. 


* Program Aystem pointer 
° Activation mark UBin(4) 
¢ Activation group mark UBin(4) 
* Invocation count UBin(4) 
* Static frame count UBin(4) 
* Program model Char(1) 


Hex 00 = original model 
Hex 01 = new mode! 
Hex 02-FF = reserved 


¢ Activation attributes Char(3) 
— Activation status bit 0 
0 = inactive 
1 = active 
— Reserved (binary 0) _ bits 1-23 


A description of the fields follows. 


rogram 
This is a pointer to the program. The system pointer returned does not contain authority. 
Within a process, a program may have more than one activation. 


activation mark 
The activation mark identifies the activation within the process. This field provides the 
actual activation mark when the special zero value was supplied for operand 2. Otherwise, 
this field has the same value as operand 2. 


activation group mark 
This identifies the activation group which contains the activation. 


invocation count 
This is a count of the number of program invocations which currently exist for this activation 
of the program. Recall that a program invocation results from a program call operation like 
Call Program not a procedure call operation like Call Bound Procedure. 


static frame count 
This is the number of static storage frames allocated for this activation. 


program model 
the model of the program. A program is either an original model (non-bound) or new model 


(bound) program. 


activation attributes 
The activation attributes identify 


¢ whether the program is active or not. Only original model program can be deactivated 
by use of the Deactivate Program instruction. 
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Materialize Activation Attributes (MATACTAT) 


Static Storage Frame List: The following information is returned when operand 3 is hex 01. This is a 

list of static storage frame descriptors. The static frame count (available in the basic activation attri- 

butes template) indicates how many entries must be accommodated by the template. The static J 
storage frame list can be materialized only if the source activation group is permitted access to the 

target activation group as determined by the activation group access protection mechanism. If access 

is not permitted, then an activation group access violation (hex 2C12) exception is signaled. 


The format of the list is: 


array(1..static frame count) of 


Static frame base 
This is a pointer to the first byte of the static frame. 


Static frame size 


Space pointer 


UBin(4) 


This is the size, in machine dependent units (currently bytes), of the static frame. 


Reserved 


Exceptions 


Exception 


06 


08 


10 


20 


22 


24 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 
Argument/parameter 


01 parameter reference violation 


Damage encountered 


04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Machine-dependent exception 
03 machine storage limit exceeded 
04 abject storage limit exceeded 


09 auxiliary storage pool number invalid 


Machine support 
02 machine check 


03 function check 


Object access 
02 object destroyed 


Pointer specification 


01 pointer does not exist 


Char(12) 


Operands 
1 2 3 Other 


~ Km KK 
x KK XK 
x KK OK 


*< 


X 
X 
X 
X 
X 
X 
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Exception 


2C 


32 


38 


02 pointer type invalid 
03 Pointer addressing invalid object 


Program execution 
12 Activation group access violation 


16 Activation not found 


Scalar specification 

03 Scalar value invalid 
Template specification 
03 Materialization length 
Domain specification 


01 Domain Violation 


Materialize Activation Group Attributes (MATAGPAT) 


Operands 
1 2 3 Other 
X X X X 


X X 
X 
X 
X 
X 
X 
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Materialize Activation Group Attributes (MATAGPAT) 


Materialize Activation Group Attributes (MATAGPAT) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 2 
02D3 Receiver Activation group Attribute selection 
mark 


Operand ?: Space pointer 
Operand 2: Unsigned binary(4) scalar 


Operand 3: Character(1) scalar (fixed length) 


ILE access 
MATAGPAT ( 
receiver : space pointer; 
var activation _group_mark : unsigned binary; 
var attribute selection : aggregate 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: This instruction will materialize the information selected by operand 3 for the activation 

group specified by operand 2 and return the information in the template supplied by operand 1. Ifthe ; 
activation group mark specified by operand 2 is zero, then information about the activation group asso- : 
ciated with the current invocation is returned. Jo 


In order to deal with the variable-length nature of some activation group attributes, the selection option 
is provided. All of the “length-of-list” type information can be gathered by selecting the first option 
described below. 
Operand 3 can have the following values: 

e hex 00 — basic activation group attributes 

e hex 01 — activation group heap list option 


e hex 02 — program activation list option 
Any value for operand 3 other than those listed will cause a sca/ar value invalid (hex 3203) exception. 


The materialization template identified by operand 1 must be 16-byte aligned in the space. This 
materialization template has the following format: 


e« Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 
e Reserved (binary 0) Char(8) 
¢ Returned information Char(") 
The number of bytes provided indicates the number of bytes provided for returned information by , 
the user of the instruction. In all cases if the number of bytes provided is less than 8, then a a 


materialization length (hex 3803) exception will be signaled. 
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Materialize Activation Group Attributes (MATAGPAT) 


The number of bytes available is set by the instruction to indicate the actual number of bytes avail- 


able to be returned. 
available. 


The format of returned information is described in the following paragraphs. 


In no case does the instruction return more bytes of information than those 


Basic Activation Group Attributes: The following information is returned when operand 3 is hex 00. 


Root program 

Reserved (binary Q) 
Storage address recycling key 
Activation group name 
Reserved (binary 0) 
Activation group mark 
Reserved (binary 0) 

Heap space count 
Activation count 

Static storage size 
Automatic storage size 
Attributes 

— Reserved 

— Activation group state. 


0 
4 


user 
system 


ll 


— Is activation group named? 


0 = no 
1 = yes 
— Destroy pending? 
0 = no 
1 = yes 


— Reserved (binary 0) 
Process access group membership advisory attributes 
— Automatic storage 


0 do not create in PAG 
1 = permit creation in PAG 


— Static storage 


0 = do not create in PAG 
1 = permit creation in PAG 


— Default heap storage 


0 = do not create in PAG 
1 = permit creation in PAG 


— Reserved (binary 0) 


Additional Description 


System pointer or null 


Char(16) 


System pointer or null 


Char(30) 
Char(2) 
UBin(4) 
Char(4) 
UBin(4) 
UBin(4) 
UBin(4) 
UBin(4) 
Char(1) 
Bit 0 
Bit 1 


Bit 2 


Bit 3 


Bits 4-7 
Char(1) 
Bit O 


Bit 1 


Bit 2 


Bits 3-7 
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Materialize Activation Group Attributes (MATAGPAT) 


root program 
those activation groups which are created by the machine (the default activation groups) 


do not have root programs, in which case this field is null. 


storage address recycling key 
a system pointer is returned only if the activation group state is specified as user, other- 


wise the field is null. 


activation group name 
For activation groups which do not have a symbolic name, this field contains all blanks. 


heap space count 
This is the number of heap spaces currently associated with the activation group. 


activation count 
This is the number of programs which are currently active within the activation group. 


static storage size 
This is the maximum amount of static storage, in machine dependent units, which has 


been allocated to the activation group at any particular time. Note that this does not nec- 
essarily reflect the amount of storage currently in use. 


automatic storage size 
This is the maximum amount of automatic storage, in machine dependent units, which 


has been allocated to the activation group at any particular time. Note that this does not 
necessarily reflect the amount of storage currently in use. It is merely a measure of the 
maximum “depth” the automatic storage stack has had to this point. 


is activation group named? 
Indicates whether the activation group is named or unnamed. The activation group name 


field contains blanks for unnamed an activation groups. The default activation groups and 
those created with the “unnamed” attribute are unnamed. 


Activation Group Heap List: When operand 3 is hex 01, the format of the returned information is an 
array of heap identifiers. This is a list of the heaps which are currently associated with the activation 
group. The heap space count (available in the basic template) indicates how many entries must be 
accommodated by the template. The format of the list is: 


¢ array(1..4eap space count) of Bin(4) 


Information about a specific heap may be obtained from the Materialize Heap Space Attributes 
(MATHSAT) instruction. 


Program Activation List! When operand 3 is hex 02, the format of the returned information is an array 
of activation marks. Each activation mark represents a program activation within the activation group. 
(The activation mark is a number which uniquely identifies the activation within a process.) The acti- 
vation count (available in the basic template) indicates how many entries must be accommodated by 
the template. The format of the list is: 


¢ array(1..activation count) of UBin(4) 


Information about a specific activation may be obtained from the Materialize Activation Attributes 
(MATACTAT) instruction. 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation Xx X Xx 
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Modify Automatic Storage Allocation (MODASA) 


Exception 


08 


10 


1c 


20 


24 


32 


2C 


38 


02 boundary alignment 
03 range 


06 optimized addressability invalid 
Argument/parameter 


01 parameter reference violation 


Damage encountered 


04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Machine-dependent exception 
03 machine storage limit exceeded 
04 object storage limit exceeded 


09 auxiliary storage pool number invalid 


Machine support 
02 machine check 
03 function check 


Pointer specification 

01 pointer does not exist 

02 pointer type invalid 

03 Pointer addressing invalid object 


Scalar specification 

03 Scalar value invalid 
Program execution 

13 Activation group not found 
Template specification 

03 Materialization length 
Domain specification 


01 Domain Violation 


Operands 
1 2 
X X 
X X 
X X 
X X 
xX X 
X X 
X 
X 
X X 
X X 
X 
X 
Xx 
xX 


x Ke Kw 


Other 


x< 
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Modify Automatic Storage Allocation (MODASA) 


Modify Automatic Storage Allocation (MODASA) 


Op Code (Hex) Operand 1 Operand 2 
02F2 Storage allocation Modification size 


Operand 7: Space pointer data object or null. 


Operand 2: Signed binary scalar. 


ILE access 
MODASA ( 
modification size : signed binary; OR 
unsigned binary; 
) : space pointer /* storage_allocation */ 


Description: The automatic storage frame (ASF) of the current invocation is extended or truncated by 
the size specified by operand 2. A positive value indicates that the frame is to be extended; a negative 
value indicates that the frame is to be truncated; a zero value does not change the ASF. If operand 1 
is not null, it will be treated as follows: 


e ASF extension: receives the address of the first byte of the extension. The ASF extension might not 
be contiguous with the remainder of the ASF allocation. 


e ASF truncation: Operand 1 should be null for truncation. If operand 1 is not null, then addressablity 
to the first byte of the deallocated space is returned. This value should not be used as a space 
pointer since it locates space that has been deallocated. 


e If a value of zero is specified for operand 2: the value returned is unpredictable. 


When the ASF is extended, the extension is aligned on a 16-byte boundary. An extension is not initial- 
ized. 


A scalar value invalid (nex 3203) exception is signaled if truncation amount would cause size of the ASF 
to be less than the amount of the initial allocation. 


A space pointer machine object cannot be specified for operand 1. 


Exceptions 
Operands 

Exception , 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid xX Xx 
08 Argument/parameter 

01 parameter reference violation X X 
10 Damage encountered 

04 system object damage state X X xX 

44 partial system object damage X X X 
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Exception 


1C 


20 


22 


24 


2C 


2E 


32 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 
02 object destroyed 
03 object suspended 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


08 object compressed 


Program execution 


1D automatic storage exceeded 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 
02 scalar attributes invalid 


03 scalar value invalid 


Return External (RTX) 


Operands 
1 2 Other 


X 

X 

X 
X X 
X X 
X X 
X X 
X X 

X 

X 

X 
X X 
X 
X 
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Return External (RTX) 


Return External (RTX) 


Op Code (Hex) Operand 1 
02A1 Return point 


Operand ?: Signed binary (2) scalar or null. 


Description: The instruction terminates execution of the invocation in which the instruction is speci- 
fied. The automatic storage frame is deallocated. 


A Return External instruction can be specified within an invocation’s subinvocation, and no exception is 
signaled. 


If a higher invocation exists in the invocation hierarchy, the instruction causes execution to resume in 
the preceding invocation in the process’ invocation hierarchy at an instruction location indirectly speci- 
fied by operand 1. If operand 1 is binary O or null, the next instruction following the Call External 
instruction from which control was relinquished in the preceding invocation in the hierarchy is given 
execution control. If the value of operand 1 is not 0, the value represents an index into the instruction 
definition list (IDL) specified as the return list operand in the Call External instruction, and the value 
causes control to be passed to the instruction referenced by the corresponding IDL entry. The first IDL 
entry is referenced by a value of one. If operand 1 is not 0 and no return list was specified in the Call 
External instruction, or if the value of operand 1 exceeds the number of entries in the IDL, or if the 
value is negative, a return point invalid (hex 2C02) exception is signaled. 


If a higher invocation does not exist, the Return External instruction causes termination of the current 
process state. If operand 1 is not 0 and is not null, the return point invalid (hex 2CQ2) exception is 
signaled. Refer to the Terminate Process instruction for the functions performed in process termi- 
nation. 


If the returning invocation has received control to process an event, then control is returned to the 
point where the event handler was invoked. In this case, if operand 4 is not 0 and is not null, then a 
return point invalid (hex 2CO2) exception is signaled. 


If the returning invocation has received control from the machine to process an exception, the return 
instruction invalid (hex 2CQ2) exception is signaled. 


If the returning invocation has an activation, the invocation count in the activation is decremented by 1. 


If the returning invocation currently has an invocation exit set, the invocation exit is not given control 
and is implicitly cleared. 


Exceptions 
Operand 

Exception 1 Other 
06 Addressing 

01 space addressing violation X 

02 boundary alignment X 

03 range X 

06 optimized addressability invalid X 
08 Argument/parameter 

01 parameter reference violation X 
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Exception 


10 


1c 


20 


22 


24 


2C 


2E 


36 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 
01 return instruction invalid 


02 return point invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Set Argument List Length (SETALLEN) 


Operand 
1 Other 
X X 
X X 
X 

X 

X 
X 
X X 
X 

X 
X X 
X X 

X 
X 

X 

X 
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set Argument List Length (SETALLEN) 


Set Argument List Length (SETALLEN) 


Op Code (Hex) Operand 1 QOperand 2 
0242 Argument list Length 


Operand 1: Operand list. 
Operand 2: Binary scalar. 


Description This instruction specifies the number of arguments to be passed on a succeeding Call 
External or Transfer Control instruction. The current length of the variable-length operand list (used as 
an argument list) specified by operand 1 is modified to the value indicated in the binary scalar speci- 
fied by operand 2. This length value specifies the number of arguments (starting from the first) to be 
passed from the list when the operand list is referenced on a Cail External or Transfer Control instruc- 
tion.: Only variable-length operand lists with the argument list attribute may be modified by the 
instruction. 


The value in operand 2 may range from 0 (meaning no arguments are to be passed) to the maximum 
size specified in the ODT definition of the operand list (meaning all defined arguments are to be 
passed). 


The length of the argument list remains in effect for the duration of the current invocation or until a Set 
Argument List Length instruction is issued against this operand list. 


Exceptions 
ra 
Operands ' 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x K K XK 


06 optimized addressability invalid 


08 Argument/parameter 
01 parameter reference violation X 


03 argument list length modification violation X 


10 Damage encountered 
04 system object damage state X X X 
44 partial system object damage X X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check 4 
03 function check X 


22 Object access | 
01 object not found X 2 | 
02 object destroyed Xx 


Chapter 9. Program Execution Instructions 9-28 


Exception 


24 


2E 


32 


36 


03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Set Invocation Exit (SETIEXIT) 


Operands 
1 2 Other 
X 
X 
X 
X 
X 
X 
X 
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Set Invocation Exit (SETIEXIT) 


Set Invocation Exit (SETIEXIT) 


Op Code (Hex) Operand 1 Operand 2 
0252 Invocation exit Argument list 
program 


Operand 1: System pointer 
Operand 2: Operand list or null 


Description: This instruction allows the external entry point of the program specified by operand 1 to 
be given control when the requesting invocation is destroyed due to normal exception handling 
actions, or due to any process termination. Normal exception handling actions are considered to be 
those actions performed by the Return From Exception (RTNEXCP) or the Signal Exception (SIGEXCP) 
instructions. 


Operand 1 is a system pointer addressing the program that is to receive control. The operand 1 
system pointer must be in either the static or automatic storage of the program invoking this instruc- 
tion. 


Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation exit 
program being called. If operand 2 is null, no arguments are passed to the invocation. 


No operand verification takes place when this instruction is executed. Nor are copies made of the 
operands, so changes made to the operand values after execution of this instruction will be used 
during later operand verification. Operand verification occurs on the original form of the operands 
when the invocation exit program is invoked. At that time operational authorization to the invocation 
exit program and retrieve authorization to any contexts referenced for materialization take place. Also, 
materialization lock enforcement occurs to contexts referenced for materialization. 


If an invocation exit program currently exists for the requesting invocation, it is replaced, and no 
exception is signaled. The invocation exit set by this instruction is implicitly cleared when the invoca- 
tion exit program is given control, or the program which set the invocation exit completes execution. 


If any invocations are to be destroyed due to normal exception handling actions, then those invocation 
exit programs associated with the invocations to be destroyed are given control before execution pro- 
ceeds to the signaled exception handler. 


A failure to invoke program (hex 0011,04,01) event is signaled when both of the following conditions 
occur: 


¢« Exception management is destroying an invocation stack due to a Signal Exception instruction, a 
Return From Exception instruction, or process termination. 


« An invocation exit program is to be destroyed due to a second Signal Exception or a second Return 
From Exception instruction. 


The invocation exit program that is being destroyed is terminated, and its associated invocation exe- 
cution is terminated. Termination of invocations due to a previous Signal Exception instruction, a 
Return From Exception instruction, or a process termination is then resumed. 


lf a process phase is terminated and the process was not in termination phase, then the invocations 
are terminated. Invocation exit programs set for the terminated invocations are allowed to run. lf an 
invocation to be terminated is an invocation exit program, then the following occurs: 


¢ A failure to invoke program (hex 0011,04,01) event is signaled. 


« If an invocation exit has been set for this invocation exit, it is allowed to run. 
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¢ The invocation exit is terminated and the associated invocation is terminated (the invocation exit is 


not reinvoked), 


Invocation exit programs for the remaining invocations to be terminated are then allowed to run. 


Exceptions 


Exception 


06 


08 


10 


1c 


20 


22 


2E 


32 


36 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 


08 object compressed 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


X 

X 

X 

X 

X 
X 
X 
X 
X 
X 
X 
X 

X 
X 
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Store Parameter List Length (STPLLEN) 


Op Code (Hex) Operand 1 J 
0241 Length 


Operand ?: Binary variable scalar. 


Description: A value is returned in operand 1 that represents the number of parameters associated 
with the invocation’s external entry point for which arguments have been passed on the preceding Call 
External or Transfer Control instruction. 


The value can range from 0 (no parameters were received) to the maximum size possible for the 
parameter list associated with the external entry point. 


Exceptions 
Operand 
Exception 1 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK OK 


06 optimized addressability invalid 


08 Argument/parameter Z 


01 parameter reference violation Xx ) 


10 Damage encountered 
04 system object damage state X X 
44 partial system object damage X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check »4 
03 function check ».4 


22 Object access 
01 object not found X 


x 


02 object destroyed 
03 object suspended X 
08 object compressed X 


24 Pointer specification 
01 pointer does not exist X 


02 pointer type invalid X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
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Operand 
Exception 1 Other 
( 01 scalar type invalid X 
02 scalar attributes invalid X 
36 Space management 
01 space extension/truncation X 


Chapter 9. Program Execution instructions 9-33 


Transfer Control (XCTL) 


Transfer Control (XCTL) 


Op Code (Hex) Operand 1 Operand 2 
0282 Program to be Argument list 
called or Call tem- 
plate 


Operand 1: System pointer or Space pointer Data Object. 
Operand 2: Operand list or null. 


Description: The instruction destroys the calling invocation and passes control to either the program 
entry procedure of a bound program or the external entry point of a non-bound program. If operand 1 
specifies a bound program that does not contain a program entry procedure, an invalid operation for 
program (hex 2C15) exception is signaled. 


Operand 1 may be specified as a system pointer which directly addresses the program that is to 
receive control or as a space pointer to a call template which identifies the program to receive control. 
Specifying a template allows for additional controls over how the specified program is to be invoked. 
The format of the call template is the following: 


¢« Call options Char(4) 
— Suppress adopted user profiles Bit 0 
0 =n0 
1 =yes 
— Reserved (binary 0) Bit 1-30 
— Force program state to user state for transfer Bit 31 
Q =n0 
1 =~yes 
« Reserved (binary 0) Char(12) 
« Program to be called System Pointer 


The suppress adopted user profiles option specifies whether or not the program adopted and propa- 
gated user profiles which may be serving as sources of authority to the process are to be suppressed 
from supplying authority to the new invocation. Specifying yes causes the propagation of adopted user 
profiles to be stopped as of the calling invocation, thereby, not allowing the called invocation to benefit 
from their authority. Specifying no allows the normal propagation of adopted and propagated user 
profiles to occur. The called program may adopt its owning user profile, if necessary, to supplement 
the authority available to its invocation. 


The force program state to user state for transfer option specifies whether or not the transfer control 
needs to be done in the current program state or as though the transfering program were running in 
the user state without the transferring program changing to run in the user state. 


If the transferring invocation has an activation, the invocation count is decremented by 1. 


Common Program Call Processing: The details of processing differ for non-bound and bound pro- 
grams. The following outlines the common steps. 


1. A check is made to determine if the caller has authority to invoke the program and that the object 
is indeed a program object. The specified program must be either a bound program that contains 
a program entry procedure or a non-bound program. 
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2. The activation group in which the program is to be run is located or created if it doesn’t exist. The 
activation group supplies the storage resources required for program execution: static, automatic, 
and heap storage. 


3. If the program requires an activation entry and it is not already active within the appropriate acti- 
vation group, it is activated. Bound programs always require an activation; non-bound programs 
require an activation only if they use static storage. The invocation count of a newly created acti- 
vation is set to 1 while the invocation count of an existing activation is incremented by 1. 


4. The invocation created for the target program has the following attributes (as would be reported 
via the Materialize Invocation Attributes instruction.) 


e the invocation mark is one higher than the current mark count value maintained for the 
process. lf the program was activated as a result of the call then its invocation mark will equal 
the activation mark, otherwise the invocation mark is larger than the activation mark. 


Note: The so-called mark counts are generated from a counter maintained for the process. 
Each time a mark is required the counter is incremented. The mark counts thus form a 
non-decreasing sequence of unique identifiers which can be used to distinguish the time 
ordering of activations, invocations, and activation groups. 


e the invocation number is the same as the invocation number of the transferring invocation. 
e the invocation type is hex 02 to indicate a XCTL type of invocation. 

5. The automatic storage frame (ASF), if required, is allocated on a 16-byte boundary. 

6. Control is transferred to the program entry procedure (or external entry point) of the program. 


7. Normal flow-of-contro! resume at the instruction following the caller of the program issuing the 
XCTL instruction. 


The details of locating the target activation group and activating the program differ depending upon the 
model of the program. 


Bound Program: A bound program is activated and run in an activation group specified by program 
attributes. There are two logical steps involved: 


e locate the existing, or create a new activation group for the program 


e locate an existing, or create a new activation entry for the program within the activation group 


After locating the activation entry for the program, control is passed to the program entry procedure for 
the program. If required, the activation group is destroyed when the invocation for the program entry 
procedure is destroyed. 


Non-bound Program: The automatic storage frame begins with a 64 byte header. if the program 
defines no automatic data items the frame consists solely of the 64-byte header, otherwise the auto- 
matic storage items are located immediately following the header. In prior releases of the machine, 
this header contained invocation information which is now available via the Materialize Invocation 
Attributes (MATINVAT) instruction. This header is not initialized and the contents of the header are not 
used by the machine. (The space is allocated merely to provide for compatibility with prior implemen- 
tations of the machine.) The update PASA stack program attribute, supported in prior implementations 
of the machine, is no longer meaningful and is ignored, if specified as an attribute of the program. 


Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation to 
which control is being transferred. Automatic objects allocated by the transferring invocation are 
destroyed as a result of the transfer operation and, therefore, cannot be passed as arguments. A 
parameter list length (hex 0802) exception is signaled if the number of arguments passed does not cor- 
respond to the number required by the parameter list of the target program. 
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If the transferring invocation has received control to process an exception, or an invocation exit. the 


return instruction invalid (hex 2C01) exception is signaled. 


If the transferring invocation currently has an invocation exit set, the invocation exit is not given control 


and is implicitly cleared. 


Authorization Required 
¢ QOperand 1 

— Operational 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 


Exception 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 
06 optimized addressability invalid 


08 Argument/parameter 
01 parameter reference violation 


02 parameter list length violation 


0A Authorization 


01 unauthorized for operation 


10 Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


1A Lock state 
01 invalid lock state 


1C Machine-dependent exception 
02 program limitation exceeded 


03 machine storage limit exceeded 


20 Machine support 
02 machine check 


03 function check 


22 Object access 


Operands 
1 2 Other 


X 

X 

X 

X 
X 

X 

X 

X X X 
X 

X X X 

X 
X 
X 
X 
X 
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2 


C 


c 


Exception 


24 


2C 


2E 


36 


38 


01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Program execution 

01 return instruction invalid 

15 invalid operation for program 
1D automatic storage overflow 
1E activation access violation 
1F program signature violation 
20 static storage overflow 

21 program import invalid 

22 data reference invalid 

23 imported object invalid 

24 activation group export conflict 


25 import not found 


Resource control limit 


01 user profile storage limit exceeded 


Space management 
01 space extension/truncation 
Template specification 


01 template value invalid 


Transfer Control (XCTL) 


Operands 

1 2 Other 

X 

X 

X 
X 
X 

X 

X 

X 
X 

X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 

X 


Chapter 9. Program Execution Instructions 


9-37 


Program Creation Control Instructions 


Chapter 10. Program Creation Control Instructions 


This chapter describes all the instructions used to control the create program function. These 
instructions are arranged in alphabetic order. For an alphabetic summary of all the instructions, see 
Appendix A, “Instruction Summary.” 


No Operation ( NOOR) * «2.26 4-4: ee eee ee ee oe ee ee See SS hae OR SOARS ee 10-3 
No Operation and. Skin {NOOPS):) se e-s-d wk be eA bee Bee es Re hw Pe KES 10-4 
Override Program Attributes (OVRPGATR) ........0 0.000. 2 10-5 
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No Operation (NOOP) 


No Operation (NOOP) 2 


Op Code (Hex) 
0000 


Description: No function is performed. The instruction consists of an operation code and no oper- 
ands. The instruction may not be branched to and is not counted as an instruction in the instruction 
stream. The instruction may be used for inserting gaps in the instruction stream. These gaps allow 
instructions with adjacent instruction addresses to be physically separated. 


The instruction may precede or follow any machine instruction except the End instruction, and any 
number of No Operation instructions may exist in succession. 
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No Operation and Skip (NOOPS) 


Op Code (Hex) Operand 1 
0001 Skip count 


Operand ?: Unsigned immediate value. 


Description: This instruction performs no function other than to indicate a specific number of bytes 
within the instruction stream that are to be skipped during encapsulation. It consists of an operation 
code and 1 operand. Operand 1 is an unsigned immediate value that contains the number of bytes 
between this instruction and the next instruction to be processed. These bytes are skipped during the 
encapsulation of this program. A value of zero for operand 1 indicates that no bytes are to be skipped 
between this instruction and the next instruction to be processed. 


If the operand 1 skip count indicates that the next instruction to process is beyond the end of the 
instruction stream, an invalid operand value range exception is signaled. 


This instruction may be used to insert gaps in the instruction stream in such a manner that allows 
instructions with adjacent instruction addresses to not be physically adjacent. 


This instruction may not be branched to, and is not counted as an instruction in the instruction stream. 


The instruction may precede or follow any machine instruction except the End instruction, and any 
number of No Operation and Skip instructions may exist in succession. 


Note: When this instruction is used in an existing program template, the following items within the 
template may be adversely affected: 


¢« The actual count of instructions may be altered to be different than the count of instructions 
that is specified in the program template header. 


¢ Object definitions that reference instructions may now be out of range or may not reference 
the intended instruction. 


The actual number of bytes skipped includes the bytes containing the instruction pius the number of 
bytes specified by the skip count value. The number of bytes skipped per template version is as 
follows: 


« Version 0 = 4 plus the skip count value. 


« Version 1 = 5 plus the skip count value. 
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Override Program Attributes (OVRPGATR) 


Op Code (Hex) Operand 1 Operand 2 
0006 Attribute identifi- Attribute modifier 
cation 


Operand ?: Unsigned immediate value. 
Operand 2: Unsigned immediate value. 


Description: This program creation control instruction allows one of a set of program attributes speci- 
fied below to be overridden. The overridden program attribute is in effect until it is changed by 
another OVRPGATR instruction. The initial program attributes are set to the ones given in the program 
template for the Create Program (CRTPG) instruction. These same initial program attributes are the 
ones that are materialized when a Material Program (MATPG) is done. That is, the OVRPGATR 
instruction has no effect on the materialized attributes. 


The OVRPGATR instruction consists of an operation code and two operands. Operand 1 is an 
unsigned immediate value that contains a representation of which program attribute is to be over- 
ridden. Operand 2 is an unsigned immediate value that contains a representation of how the program 
attribute is to be overridden. 


This instruction may not be branched to, and is not counted as an instruction in the instruction stream. 
The instruction may precede or follow any machine instruction. 


The program attributes defined by operand 1 is overridden according to the following selection values: : 


Attribute Attribute 
Identification Description 


1 Array constrainment attribute 
Allowed values for operand 2: 
1 = Constrain array references 
2 = Do not constrain array references 
3 = Fully unconstrain array references 
4 


= Terminate override of array constrainment attributes and resume use of the 
attributes specified in the program template 


2 String constrainment attribute 


Allowed values for operand 2: 


1 = Constrain string references 
2 = Do not constrain string references 
3 = Terminate override of string constrainment attribute and resume use of the 
attribute specified in the program template 
3 Suppress binary size exception attribute 


Allowed values for operand 2: 
1 = Suppress binary size exceptions 
2 = Do not suppress binary size exceptions J 
3 = Terminate override of suppression of binary size exception attribute and 
resume use of the attribute specified in the program template 
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Suppress decimal data exception attribute 
Allowed values for operand 2: 
' 
2 
3 


II 


Suppress decimal data exceptions 


Do not suppress decimal data exceptions 


Terminate override of suppression of decimal data exception attribute and 
resume use Of the attribute specified in the program template 


Copy Bytes with Pointers (CPYBWP) alignment data check attribute 
Allowed values for operand 2: 
1 = Constrain CPYBWP to require like alignment of operands (default) 
2 = Do not constrain CPWBWP to require like alignment of operands 
Compare Pointer for Space Addressibility (CMPPSPAD) null pointer tolerance attribute 
Allowed values for operand 2: 
1 = Signal pointer does not exist exceptions for operands 1 and 2 (default) 


2 = Do not signal pointer does not exist exceptions for operands 1 and 2 
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Chapter 11. Independent Index Instructions 


This chapter describes the instructions used for indexes. These instructions are in. alphabetic order. 
For an alphabetic summary of all the instructions, see Appendix A, “Instruction Summary.” 


Create Independent Index (CRTINX) ... 2... 0... 0. cc 11-3 
Destroy Independent Index (DESINX) ............0 0.00000. 000 0 ee eee 11-10 
Find Independent Index Entry (FNDINXEN) ... 20... 0.0... ce ee ee ee 11-12 
Insert Independent Index Entry (INSINXEN) .......0.0.0.0. 0... 02.0 ee es 11-16 
Materialize Independent Index Attributes (MATINXAT) .............. 0.0002 ee eee 11-19 
Modify Independent Index (MODINX) .......0.. 20.0000 2 ee ee 11-23 
Remove Independent Index Entry (RMVINXEN) ....... ee Mis ie ces a Ge ee oes ee A 11-26 
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Create Independent Index (CRTINX) 


Op Code (Hex) Operand 1 Operand 2 
Index description 
template 


0446 Index 


Operand f: System pointer. 


Operand 2: Space pointer. 


ILE access 


CRTINX ( 
var index : system pointer; 
description_template : space pointer 


Create Independent Index (CRTINX) 


Description: This instruction creates an independent index based on the index template specified by 
operand 2 and returns addressability to the index in a system pointer stored in the addressing object 


specified by operand 1. 


The format of the index description template described by operand 2 is as follows (must be aligned on 


a 16-byte multiple): 


« Template size specification 


— Number of bytes provided for materialization 


— Number of bytes available for materialization 


¢ Object identification 
— Object type 
— Object subtype 
— Object name 
¢ Object creation options 
— Existence attributes 


0 = Temporary 
1 = Permanent 


— Space attribute 


O = Fixed-length 
= Variable-length 


— {nitial context 


0 = Do not insert addressability in context 


1 


— Access group 


Insert addressability in context 


0 = Do not create as member of access group 


1 = Create as member of access group 
— Reserved (binary 0) 
— Initialize space 


0 = Initialize 


Char(8) 

Bin(4)* om 
Bin(4)* ~d 
Char(32) 

Char(1)* 

Char(1) 

Char(30) 

Char(4) 

Bit 0 


Bit 1 
Bit 2 


Bit 3 


Bits 4-12 wa 


Bit 13 
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1 = Do not initialize 


Reserved (binary OQ) 


Recovery options 


Reserved (binary 0) 
ASP number 


Size of space 


Initial value of space 


Performance class 


— 


Space alignment 


Bits 14-31 
Char(4) 
Char(2) 
Char(2) 
Bin(4) 
Char(1) 
Char(4) 
Bit 0 


O = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, 0 must be spec- 


ified for the performance class. 


1 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space as well as to allow proper alignment of input/output 


buffers at 512-byte alignments within the the space. 
Reserved (binary 0) 
Main storage pool selection 


0 = Process default main storage pool is used for object. 
1 = Machine default main storage pool is used for object. 


Reserved (binary 0) 


Block transfer on implicit access state modification 


Bits 1-4 
Bit 5 


Bit 6 
Bit 7 


= Transfer the minimum storage transfer size for this object. This value is 1 storage unit. 
1 = Transfer the machine default storage transfer size. This value is 8 storage units. 


Reserved (binary 0) 


Reserved (binary 0) 


Extension offset 
Context 


Access group 


Index attributes 


Entry length attribute 


0 = Fixed-length entries 
1 = Variable-length entries 


Immediate update 


0 = No immediate update 
1 = Immediate update 
Key insertion 

0 = No insertion by key 

1 = Insertion by key 


Entry format 


0 = Scalar data only 
1 = Both pointers and scalar data 


Optimized processing mode 


Chapter 11. 


Bits 8-31 
Char(3) 

Bin(4) 

System pointer 
System pointer 
Char(1) 

Bit O 


Bit 1 


Bit 2 


Bit 3 


Bit 4 
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0 = Optimize for random references 
1 = Optimize for sequential references 
— Maximum entry length Bit 5 
0 = Maximum entry length is 120 bytes 
1 = Maximum entry length is 2000 bytes 
— Reserved (binary 0) Bits 6-7 
e Argument length Bin(2) 
e Key length Bin(2) 


Note: This instruction ignores the values associated with the entries annotated with an asterisk (*). 


The template identified by operand 2 must be 16-byte aligned. 


The template extension is located by the extension offset field. The template extension must be 
16-byte aligned in the space. The following is the format of the template extension: 


e Reserved (binary 0) Char(20) 
« Domain assigned to the object Char(2) 
¢« Reserved (binary 0) Char(42) 


If the created object is permanent, it is owned by the user profile governing process execution. The 
owning user profile is implicitly assigned all private authority states for the object. The storage occu- 
pied by the created object is charged to this owning user profile. If the created object is temporary, 
there is no owning user profile, and all authority states are assigned as public. Storage occupied by 
the created context is charged to the creating process. 


The object identification specifies the symbolic name that identifies the space within the machine. An 
object type of hex OE is implicitly supplied by the machine. The object identification is used to identify 
the object on materialize instructions as well as to locate the object in a context that addresses the 
object. 


The existence attribute specifies that the index is to be created as a permanent or a temporary object. 
A temporary index, if not explicitly destroyed by the user, is implicitly destroyed by the machine when 
machine processing is terminated. 


A space may be associated with the created object. The space may be fixed or variable in size, as 
specified by the space attribute field. The initial allocation is as specified in the size of space field. 
The machine allocates a space of at least the size specified. The actual size allocated is dependent on 
an algorithm defined by a specific implementation. 


If the initial context creation attribute field indicates that addressability is to be inserted in a context, 
the context field must be a system pointer that identifies a context where addressability to the newly 
created object is to be placed. If the initial context indicates that addressability is not to be placed in a 
context, the context field is ignored. 


If the access group creation attribute field indicates that the object is to be created in an access group, 
the access group field must be a system pointer that identifies an access group in which the object is 
to be created. The existence attribute of the object must be identical to the existence attribute of the 

access group. If the object is not to be created in the access group, the access group field is ignored. 


The initialize space creation option controls whether or not the space is to be initialized. When initialize 
is specified, each byte of the space is initialized to a value specified by the initial value of space field. 
Additionally, when the space is extended in size, this byte value is also used to initialize the new allo- 
cation. When do not initialize is specified, the initial value of space field is ignored and the initial value 
of the bytes of the space are unpredictable. 
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When do not initialize is specified for a space, internal machine algorithms do ensure that any storage 
resources last used for allocations to another object which are reused to satisfy allocations for the 

cj space are reset to a machine default value to avoid possible access of data which may have been 
stored in the other object. To the contrary, reusage of storage areas previously used by the space 
object are not reset. thereby exposing subsequent reallocations of those storage areas within the 
space to access of the data which was previously stored within them. 


The ASP number attribute specifies the ASP number of the ASP on which the unit is to be allocated. A 
value of 0 indicates an ASP number is not specified and results in the default of allocating the object in 
the system ASP. Allocation on the system ASP can only be done implicitly by not specifying an ASP 
number. The only nonzero values allowed are 2 through 16 which provide for explicit allocation of 
Objects on user ASPs. The ASP number must specify an existing ASP. The ASP number attribute may 
only be specified for creation of a permanent object. The ASP number attribute of an object can be 
materialized, but cannot be modified. 


Invalid specification of the ASP number attribute results in the signaling of the template value invalid 
(hex 3801) exception. 


The preferred unit number attribute which can be specified in the performance class field at object cre- 
ation may not be specified in conjunction with specification of the ASP number attribute. 


The performance class parameter provides information allowing the machine to more effectively 
manage the object considering the overall performance objectives of operations involving the index. 


If the entry length attribute field specifies fixed-length entries, the entry length of every index entry is 

established at creation by the value in the argument length field of the index description template. If 

the entry length attribute field specifies variable-length entries, then entries will be variable-length (the 
S length of each entry is supplied when the entry is inserted), and the argument length field is ignored. 


lf the immediate update field specifies that an immediate update should occur, then every update to the 
index will be written to auxiliary storage after every insert or remove operation. 


If the key insertion field specifies insertion by key, then the key length field must be specified. This 
allows the specification of a portion of the argument (the key), which may be manipulated in either of 
the following ways in the Insert Index Entry instruction: 


e The insert will not take place if the key portion of the argument is already in the index. 


e The insert will cause the nonkey portion of the argument to be replaced if the key is already in the 
index. 


The entry format field designates the index entries as containing both pointers and scalar data or 
scalar data only. The both pointers and scalar data field can be used only for indexes with fixed-length 
entries. If the index is created to contain both pointers and data, then 


e Entries to be inserted must be 16-byte aligned. 


e Each entry retrieved by the Find Independent Index Entry instruction or the Remove Independent 
Index Entry is 16-byte aligned. 


e Pointers are allowed in both the key and nonkey portions of an index entry. 
e Pointers need not be at the same location in every index entry. 
e Pointers inserted into the index remain unchanged. No resolution is performed before insertion. 
If the index is created to contain scalar data only, then: 
Cc e Entries to be inserted need not be aligned. 


e Entries returned by the Find Independent Index Entry instruction or the Remove Independent Index 
Entry instruction are not aligned. 
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e Any pointers inserted into the index will be invalidated. 


The optimized processing mode index attribute field is used to designate whether the index should be J 
created and maintained in a manner that optimizes performance for either random or sequential oper- ww 


ations. 


If the maximum entry length attribute field specifies that the maximum entry length is 2000 bytes, then 
the maximum length allowed for independent index entries will be 2000 bytes. Otherwise, the 
maximum entry length allowed will be 120 bytes. 


The key length field specifies the length of the key for the entries that are inserted into the index. The 
argument length specifies the length of the the entries when fixed length entries are used. 


The key /ength must have a value less than or equal to the argument length whether specified during 
creation (for fixed-length entries) or during insertion (for variable length). The key /ength is not used if 
the key insertion field specifies no insertion by key. 


The extension offset specifies the byte offset from the beginning of the operand 2 template to the 
beginning of the template extension. An offset value of zero specifies that the template extension is 
not provided. A negative offset value is invalid. A non-zero offset must be a multiple of 16 (to cause 
16 byte alignment of the extension). Except for these restrictions, the offset value is not verified for 
correctness relative to the location of other portions of the create template. 


The domain assigned field in the template extension allows the user of this instruction to override the 
domain for this object that would otherwise be chosen by the machine. Valid values for this field are: 


Domain field Domain assigned to the object 

Hex 0000 The domain will be chosen by the machine. Ps 
Hex 0001 The domain will be “Common User’. a 
Hex 8000 The domain will be ‘Common System’. 


Any value specified for the domain assigned field other than those listed above will result in a template 
value invalid (hex 3801) exception being signalled. 


Limitations: The following are limits that apply to the functions performed by this instruction. 


The size of the object specific portion of the object is limited to a maximum of 4 gigabytes. This size is 
dependent upon the amount of storage needed for the number and size of index entries and exciudes 
the size of the associated space, if any. 


The size of the associated space for this object is limited to a maximum of 16MB-32 bytes. 


Authorization Required 
e Insert 
— Context identified by operand 2 
— User profile of object owner 
¢ Retrieve 


— Contexts referenced for address resolution 
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Lock Enforcement 


C ° Modify 


— Access group identified by operand 2 


User profile of object owner 


Context identified by operand 2 


Materialize 


Contexts referenced for address resolution 


Exceptions 


Exception 


02 


06 


08 


0A 


OE 


10 


1A 


20 


22 


Access group 
01 object ineligible for access group 


02 object exceeds available space 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Context 


01 duplicate object identification 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 
03 machine storage limit exceeded 
04 object storage limit exceeded 


09 auxiliary storage pool number invalid 


Machine support 
02 machine check 
03 function check 


Object access 


01 object not found 


Create Independent Index (CRTINX) 


Operands 
1 2 Other 


x KK XK 
x KK XK 


»< 


X X 
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Create Independent Index (CRTINX) 


Operands 
Exception 1 2 Other | 
02 object destroyed X Xx } 
03 object suspended X X 
07 authority verification terminated due to destroyed object X 
08 object compressed X 
24 Pointer specification 
01 pointer does not exist X X 
02 pointer type invalid X X 
03 pointer addressing invalid object X 
2E Resource control limit 
01 user profile storage limit exceeded X 
36 Space management 
01 space extension/truncation X 
38 Template specification 
01 template value invalid X 
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Destroy Independent Index (DESINX) 


Destroy Independent Index (DESINX) 


Op Code (Hex) Operand 1 
0451 Index 


Operand 7: System pointer. 


ILE access 


DESINX ( 
var index : system pointer 


) 


Description: A previously created index identified by operand 1 is destroyed, and addressability to the 
object is removed from any context in which addressability exists. The system pointer identified by 
operand 1 is not modified by the instruction, and a subsequent reference to the destroyed index 
through the pointer results in an object destroyed exception. 


Authorization Required 
e Object control 

— Operand 1 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 
— Contexts referenced for address resolution 
e Object control 
— Operand 1 
¢ Modify 
— Access group which contains operand 1 
— Context which addresses operand 1 


— User profile which owns index 


Exceptions 

Operand 
Exception 1 Other 
06 Addressing 


01 space addressing violation X 
02 boundary alignment X 
03 range x 
06 optimized addressability invalid X 


08 Argument/parameter 


01 parameter reference violation X 
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Destroy Independent Index (DESINX) 


Operand 
Exception 1 Other 


0A Authorization ; 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage state X X 


< 


05 authority verification terminated due to damaged object 


44 partial system object damage X X 


1A Lock state 


01 invalid lock state 4 


1c Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 


01 object not found X 


< 


02 object destroyed 
03 object suspended X 

07 authority verification terminated due to destroyed object X 
08 object compressed X J 


24 Pointer specification 


01 pointer does not exist X 


x< 


02 pointer type invalid 


03 pointer addressing invalid object X 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X 
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Find Independent Index Entry (FNDINXEN) 


Find Independent Index Entry (FNDINXEN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
0494 Receiver Index Option list Search argument 


Operand f: Space pointer. 
Operand 2: System pointer. 
Operand 3: Space pointer. 


Operand 4: Space pointer. 


ILE access 
FNDINXEN ( 
receiver : space pointer; 
var index : system pointer; 
option list : space pointer; 


search argument : space pointer 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description:. This instruction searches the independent index identified by operand 2 according to the 
search criteria specified in the option list (operand 3) and the search argument (operand 4); then it 
returns the desired entry or entries in the receiver field (operand 1). The maximum size of the inde- 
pendent index entry is either 120 bytes or 2000 bytes depending on how the maximum entry length 
attribute field was specified when the index was created. 


The option list is a variable-length area that identifies the type of search to be performed, the length of 
the search argument(s), the number of resultant arguments to be returned, the lengths of the entries 
returned, and the offsets to the entries within the receiver identified by the operand 1 space pointer. 
The option list has the following format: 


e Rule option Char(2) 
e Argument length UBin(2) 
e Argument offset Bin(2) 
« Occurrence count | Bin(2) 
e Return count Bin(2) 
Each entry that is returned to the receiver operand contains the following: 
¢ Entry length UBin(2) 
e Offset Bin(2) 


The rule option identifies the type of search to be performed and has the following meaning: 


Search Type Value (Hex) Meaning 

nd 0001 Find equal occurrences of operand 4. 

> 0002 Find occurrences that are greater than 
operand 4. 
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Find Independent Index Entry (FNDINXEN) 


Search Type Value (Hex) Meaning 

< 0003 Find occurrences that are less than 
operand 4. 

> 0004 Find occurrences that are greater than or 
equal to operand 4. 

< 0005 Find occurrences that are less than or 
equal to operand 4. 

First 0006 Find the first index entry or entries. 

Last 0007 Find the last index entry or entries. 

Between 0008 Find all entries between the two argu- 


ments specified by operand 4 (inclusive). 


The rule option to find between requires that operand 4 be a 2-element array in which element 1 is the 
starting argument and element 2 is the ending argument. All arguments between (and including) the 
starting and ending arguments are returned, but the occurrence count specified is not exceeded. 


If the index was created to contain both pointers and scalar data, then the search argument must be 
16-byte aligned. For the option to find between limits, both search arguments must be 16-byte aligned. 


The rule option and the argument length determine the search criteria used for the index search. The 
argument length must be greater than or equal to one. The argument length for fixed-length entries 
must be less than or equal to the argument length specified when the index is created. 


The argument length field specifies the length of the search argument (operand 4) to be used for the 
index search. When the rule option equals first or last, the argument /ength field is ignored. For the 
rule option to find between, the argument length field specifies the lengths of one array element. The 
lengths of the array elements must be equal. 


The argument offset is the offset of the second search argument from the beginning of the entire argu- 
ment field (operand 4). The argument offset field is ignored unless the rule option is find between. 


The occurrence count specifies the maximum number of index entries that satisfy the search criteria to 
be returned. This field is limited to a maximum value of 4095. If this value is exceeded, a template 
value invalid (hex 3801) exception is signaled. 


The return count specifies the number of index entries satisfying the search criteria that were returned 
in the receiver (operand 1). If this field is 0, no index arguments satisfied the search criteria. 


There are two fields in the option list for each entry returned in the receiver (operand 1). The entry 
length is the length of the entry retrieved from the index. The offset has the following meaning: 


¢ For the first entry, the offset is the number of bytes from the beginning of the receiver (operand 1) 
to the first byte of the first entry. 


e For any succeeding entry, the offset is the number of bytes from the beginning of the immediately 
preceding entry to the first byte of the entry returned. 


The entries that are retrieved as a result of the Find Independent Index Entry instruction are always 
returned starting with the entry that is closest to or equal to the search argument and then proceeding 
away from the search argument. For example, a search that is for < (less than) or < (less than or 
equal to) returns the entries in order of decreasing value. 


All the entries that satisfy the search criteria (up to the occurrence count) are returned in the space 
starting at the location designated by the operand 1 space pointer. 


If the index was created to contain both pointers and scalar data, then each returned entry is 16-byte 
aligned. 
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Find Independent Index Entry (FNDINXEN) 


If the index was created to contain sca/ar data only, then returned entries are contiguous. 


Every entry retrieved causes the count of the find operations to be incremented by 1. The current 
value of this count is available through the Materialize Index Attributes instruction. 


Authorization Required 
e Retrieve 
— Operand 2 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 space addressing violation X X X X 
02 boundary alignment X X X X 
03 range X X X X 
06 optimized addressability invalid X X X X 
08 Argument/parameter 
01 parameter reference violation X X X X 
0A Authorization 
01 unauthorized for operation X 
10 Damage encountered 
04 system object damage state X X X X X 
05 authority verification terminated due to damaged object X 
44 partial system object damage X X X X X 
1A Lock state 
01 invalid lock state X 
1C Machine-dependent exception 
03 machine storage limit exceeded X 
20 Machine support 
02 machine check X 
03 function check X 
22 Object access 
01 abject not found X X X X 
02 object destroyed X X X X 
03 object suspended X Xx X X 
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Exception 


24 


2E 


36 


38 


Find Independent Index Entry (FNDINXEN) 


Operands 

1 2 3 4 Other 
07 authority verification terminated due to destroyed object X ) 
08 object compressed X 
Pointer specification 
01 pointer does not exist X X X X 
02 pointer type invalid X X X X 
03 pointer addressing invalid object X 
Resource control limit 
01 user profile storage limit exceeded X 
Space management 

X 


01 space extension/truncation 


Template specification 
01 template value invalid 


02 template size invalid 
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Insert Independent Index Entry (INSINXEN) 


Insert Independent Index Entry (INSINXEN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
04A3 Index Argument Option list 


Operand 1: System pointer. 
Operand 2: Space pointer. 


Operand 3: Space pointer. 


— ILE access 


; INSINXEN ( 
var index : system pointer; 
argument : space pointer; 


option_list : space pointer 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: This instruction inserts one or more new entries into the independent index identified by 
operand 1 according to the criteria specified in the option list (operand 3). Each entry is inserted into 
the index at the appropriate location based on the binary value of the argument. No other collating 
sequence is supported. The maximum length allowed for the independent index entry is either 120 
bytes or 2000 bytes depending on how the maximum entry length attribute field was specified when the 
index was created. 


The argument (operand 2) and the option list (operand 3) have the same format as the argument and 
option list for the Find Independent Index Entry instruction. 


The rule option identifies the type of insert to be performed and has the following meaning: 


Insert Type Value (Hex) Meaning Authorization 
Insert 0001 Insert unique argument Insert 
Insert with 0002 Insert argument, replacing the Update 
replacement nonkey portion if the key is 

already in the index 
Insert without 0003 Insert argument only if the key is Insert 
replacement not already in the index 


The insert rule option is valid only for indexes not containing keys. The insert with replacement rule 
option and the insert without replacement rule option are valid for indexes containing either fixed- or 
variable-length entries with keys. The duplicate key argument (hex 1801) exception is signaled for the 
following conditions: 


e If the rule option is insert and the argument to be inserted (operand 2) is already in the index 


e If the rule option is insert without replacement and the key portion of the argument to be inserted 
(operand 2) is already in the index 


The argument length and argument offset fields are ignored, however, the entry /ength and offset fields 
must be entered for every entry which is to be inserted into the index. 
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Insert Independent Index Entry (INSINXEN) 


The occurrence count specifies the number of arguments to be inserted. This field is limited to a 
maximum value of 4095. If this value is exceeded, a template value invalid (hex 3801) exception is 


signaled. J 


If the index was created to contain both pointers and data, then each entry to be inserted must be 
16-byte aligned. If the index was created to contain variable-length entries, then the entry length and 
offset fields must be specified in the option list for each argument in the space identified by operand 2. 
The entry length is the length of the entry to be inserted. 


If the index was created to contain both pointer and scalar data, the offset field in the option list must 
be supplied for each entry to be inserted. The offset is the number of bytes from the beginning of the 
previous entry to the beginning of the entry to be inserted. For the first entry, this is the offset from the 
start of the space identified by operand 2. 


The return count specifies the number of entries inserted into the index. If the index was created to 
contain scalar data only, then any pointers inserted are invalidated. 


Authorization Required 
e Insert or update depending on insert type 
— Operand 1 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 


¢ Materialize 3 


— Contexts referenced for address resolution 


e Modify 
— Operand 1 
Exceptions 
Operands 

Exception 1 2 3 Other 
02 Access group 

01 object exceeds available space X 
06 Addressing 

01 space addressing violation X X X 

02 boundary alignment X X X 

03 range X X X 

06 optimized addressability invalid X X X 
08 Argument/parameter 

01 parameter reference violation X X X 
0A Authorization 

01 unauthorized for operation X » 
10 Damage encountered 

04 system object damage state X X X X 
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Insert Independent Index Entry (INSINXEN) 


Operands 
Exception 1 2 3 Other 
05 authority verification terminated due to damaged object X 


44 partial system object damage x X X x 


18 Independent index 


01 duplicate key argument in index X 


1A Lock state 


01 invalid lock state D4 


1c Machine-dependent exception 
03 machine storage limit exceeded X 


04 object storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check 4 


22 Object access 
01 object not found X X X 


x< 
*< 
*< 


02 object destroyed 
03 object suspended x X X 
07 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 


01 pointer does not exist X X X 


x 
x< 
x 


02 pointer type invalid 


03 pointer addressing invalid object X 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X 


38 Template specification 
01 template value invalid X 


02 template size invalid X 
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Materialize Independent Index Attributes (MATINXAT) 


Materialize Independent Index Attributes (MATINXAT) 


Op Code (Hex) Operand 1 Operand 2 J 
0462 Receiver Index 


Operand ?: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATINXAT ( 
receiver : space pointer; 
var index : system pointer 


) 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: The instruction materializes the creation attributes and current operational statistics of 
the independent index identified by operand 2 into the space identified by operand 1. The format of the 
attributes materialized is as follows: 


« Materialization size specification | Char(8) 

— Number of bytes provided for materialization Bin(4) ; 

— Number of bytes available for materialization Bin(4) J 
¢« Object identification Char(32) 

— Object type Char(1) 

— Object subtype Char(1) 

— Object name Char(30) 
¢ Object creation options Char(4) 

— Existence attributes Bit O 


O = Temporary 
1 = Reserved 


— Space attribute Bit 1 


O = Fixed-length 
1 = Variable-length 


— Context Bit 2 


= Addressability not in context 
1 = Addressability in context 


— Access group Bit 3 


O = Not a member of access group 
1 = Member of access group 


— Reserved (binary 0) Bits 4-12 ) 
— Initialize space Bit 13 
— Reserved (binary 0) Bits 14-31 
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Materialize Independent Index Attributes (MATINXAT) 


*« Reserved (binary 0) Char(4) 

* Size of space Bin(4) 

e Initial value of space Char(1) 

¢« Performance class Char(4) 
— Space alignment Bit 0 


O = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, this value must 
be specified for the performance class. 

1 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space as well as to allow proper alignment of input/output 
buffers at 512-byte alignments within the the space. 


Reserved (binary 0) Bits 1-4 
Main storage pool selection Bit 5 

OQ = Process default main storage pool used for object. 

1 = Machine default main storage pool used for object. 

Reserved (binary 0) Bit 6 
Block transfer on implicit Bit 7 


access state modification 


0 = The minimum storage transfer size for this object is a value of 1 storage unit. 
1 = The machine default storage transfer size for this object is a value of 8 storage units. 


— Reserved (binary 0) 
e Reserved (binary 0) 
* Context 


e Access group 


Bits 8-31 
Char(7) 
System pointer 


system pointer 


e Index attributes Char(1) 

e Argument length Bin(2) 

e Key length Bin(2) 

e Index statistics Char(12) 
— Entries inserted UBin(4) 
— Entries removed UBin(4) 
— Find operations UBin(4) 


The first 4 bytes of the materialization identify the total number of bytes provided that may be used by 
the instruction. This value is supplied as input to the instruction and is not modified by the instruction. 
A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. 


No exceptions other than the materialization length (hex 3803) exception described previously are sig- 
naled in the event that the receiver contains insufficient area for the materialization. 
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Materialize Independent Index Attributes (MATINXAT) 


The template identified by the operand 1 space pointer must be 16-byte aligned. Values in the tem- 
plate remain the same as the values specified at the creation of the independent index except that the 
object identification, context, and size of the associated space contain current values. 


If the entry length is fixed, then the argument length is the value supplied in the template when the 
index was created. If the entry length is variable, then the argument length field is equal to the length 
of the longest entry that has ever been inserted into the index. 


The number of arguments in the index equals the number of entries inserted minus entries removed. 
The value of the find operations field is initialized to 0 each time the index is materialized. The value 
may not be correct after an abnormal system termination. 


Authorization Required 
¢ Operational 

— Operand 2 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation X X 
02 boundary alignment X X 
03 range X X 
06 optimized addressability invalid X X 
08 Argument/parameter 
01 parameter reference violation Xx X 
0A Authorization 
01 unauthorized for operation X 
10 Damage encountered 
04 system object damage state Xx X X 
05 authority verification terminated due to damaged object Xx 
44 partial system object damage X X X 
1A Lock state 
01 invalid lock state X 
1C Machine-dependent exception 
03 machine storage limit exceeded X 
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Materialize Independent Index Attributes (MATINXAT) 


Exception 


22 


24 


2E 


36 


38 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 


03 materialization length exception 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 

X 

X 
X 


Other 
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Modify Independent Index (MODINX) 


Modify Independent Index (MODINX) 


Op Code (Hex) Operand 1 Operand 2 
0452 Independent index Modification 
option 


Operand 7: System pointer. 


Operand 2: Character (4) scalar. 


ILE access 


MODINX ( 
var index : system pointer; 
var modification option : aggregate 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: This instruction modifies the selected attributes of the independent index specified by 
operand 1 to have the values specified in operand 2. The modification options specified in operand 2 
have the following format: 


¢ Modification selection Char(1) 
— Reserved (binary 0) Bit O 
— Immediate update Bit 1 


0 = Do not change immediate update attribute 
= Change immediate update attribute 


— Reserved (binary 0) Bits 2-7 
¢ New attribute value Char(1) 
— Reserved (binary 0) Bit O 
— Immediate update Bit 1 

0 = No immediate update 
1 = Immediate update 
— Reserved (binary 0) Bits 2-7 
« Reserved (binary 0) Char(2) 


If the modification selection immediate update is 0, then the immediate update attribute is not changed. 
If the modification selection immediate update bit is 1, the immediate update attribute is changed to the 


new immediate update attribute value. 


lf the immediate update attribute of the index was previously set to no immediate update, and it is 
being modified to immediate update, then the index is ensured before the attribute is modified. 


Authorization Required 
« Object management 
— Operand 1 


¢ Retrieve 
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Modify Independent Index (MODINX) 


— Contexts referenced for address resolution 


Lock Enforcement: 
* Modify 

— Operand 1 
e Materialization 


— Contexts referenced for address resolution 


Exceptions 


Operands 


Exception 1 2 Other 


06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KK XK 
x K KR MK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage X X 


~ 


05 authority verification terminated due to damaged object 


44 partial system object damage X 


1A Lock state 


01 invalid lock state X 


1¢C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check : X 


22 Object access 
01 object not found X X 
02 object destroyed 
03 object suspended X X 


~*~ 
~< 


07 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 


01 pointer does not exist X X 


x 
~*~ 


02 pointer type invalid 


03 pointer address invalid object X 
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Exception 
2E Resource control limit 


01 user profile storage limit exceeded 


32 Scalar specification 
01 scalar type invalid 


02 scalar attributes invalid 


36 Space management 


01 space extension/truncation 


Modify Independent Index (MODINX) 


Operands 
1 2 Other 
X 
X X 
X 
X 
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Remove Independent Index Entry (RMVINXEN) 


Remove Independent Index Entry (RMVINXEN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 
0484 Receiver Index Option list Argument 


Operand f: Space pointer or null. 
Operand 2: System pointer. 
Operand 3: Space pointer. 


Operand 4: Space pointer. 


ILE access 


RMVINXEN ( 
receiver : space pointer; OR 
null operand; 


var index : system pointer; 
option list : space pointer; 
argument : Space pointer 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: The index entries identified by operands 3 and 4 are removed from the independent 
index identified by operand 2 and optionally returned in the receiver specified by operand 1. The 
maximum length of an independent index entry is either 120 bytes or 2000 bytes depending on how the 
maximum entry length attribute field was specified when the index was created. 


The option list (operand 3) and the argument (operand 4) have the same format and meaning as the 
option list and argument for the Find Independent Index Entry instruction. The return count designates 
the number of index entries that were removed from the index. 


The arguments removed are returned in the receiver field if a space pointer is specified for operand 1. 
If operand 1 is null, the entries removed from the index are not returned. If neither space pointer nor 
null is specified for operand 1, the entries are returned in the same way that entries are returned for 
the Find Independent Index Entry instruction. 


Every entry removed causes the occurrence count to be incremented by 1. The current value of this 
count is available through the Materialize Index Attributes instruction. The occurrence count field must 
be less then 4096. 


Authorization Required 
¢ Delete 

— Operand 2 
e Retrieve 


— Contexts referenced for address resolution 
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Remove Independent Index Entry (RMVINXEN) 


Lock Enforcement 
¢ Materialize | 
— Contexts referenced for address resolution 
e Modify 
— OQOperand 2 


Exceptions 

Operands 
Exception 1 2 3 4 Other 
02 Access group 


01 object exceeds available space X 


06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KK XK 
x KK K 
x KK XK 
x KK RK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X. X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage state X X X X X 


x< 


05 authority verification terminated due to damaged object 


44 partial system object damage X X X X X 


1A Lock state 
01 invalid lock state D4 D4 


1C Machine-dependent exception 
03 machine storage limit exceeded X 


04 object storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check X 


22 Object access 
01 object not found X X X X 
02 object destroyed 
03 object suspended X X xX X 


07 authority verification terminated due to destroyed object X 


x< 
Pas 
x 
* 


08 object compressed X 


24 Pointer specification 


01 pointer does not exist X X X X 
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Exception 


2E 


36 


38 


02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 


02 template size invalid 


Remove Independent Index Entry (RMVINXEN) 


Operands 
1 2 3 4 Other 
X X X X 
xX 
X 
X 
X 
X 
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Queue Management Instructions 


Chapter 12. Queue Management Instructions 


This chapter describes the instructions used for queue management. These instructions are in alpha- 
betic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
summary.” 


DEGUGCUGHDEQ): c-kit. us Wien oe ae aie Soe pee a de Sw, Eee See eR So ee ee 12-3 
Pnqueue. (ENGQ): «5. 3% 6-%.0 Abas Ge eee Se Bb he eS UO OR eee 6S ee Bee eed {2-9 
Materialize Queue Attributes (MATQAT)  ........0..00.0 00000 2 ee 12-12 
Materialize Queue Messages (MATQMSG) ..........0. 0.0000. ee ee 42-16 
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Dequeue (DEQ) 


Dequeue (DEQ) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand 4-5 
DEQ Message Message text Queue or 
1033 prefix queue tem- 

plate 
DEQB Branch options Message Message text Queue or Branch targets 
1C33 prefix queue tem- 

plate 
DEQI Indicator Message Message text Queue or Indicator targets 
1833 options prefix queue tem- 

plate 


Operand 7: Character variable scalar (fixed-length). 


Operand 2: Space pointer. 


Operand 3: System pointer or space pointer data object. 


Operand 4-5: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 


number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 


DEQ ( 
var message prefix : 
message text 

var queue 


aggregate; 
: space pointer; 
: system pointer; 


) : signed binary /* return_code */ 


If a message is not available, this instruction will return 
immediately with the return code set as follows: 


Return_Code Meaning 

1 Message Dequeued. 

6 Message Not Dequeued. 

OR 

DEQWAIT ( 

var msg _ prefix : aggregate; 
msg_text : space pointer; 

var queue : system pointer 


) 


If a message is not available, this instruction will wait until a 


message is available. 
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Description: The instruction retrieves a queue message based on the queue type (FIFO, LIFO, or 
keyed) specified during the queue’s creation. If the queue was created with the keyed option, mes- 
sages can be retrieved by any of the following relationships between an enqueued message key and a 
selection key specified in operand 1 of the Dequeue instruction: #, >, <, <, and >. If the queue was 


created with either the L/FO or F/FO attribute, then only the next message can be retrieved from the 
queue. 


lf a message is not found that satisfies the dequeue selection criterion and the branch or options are 
not specified, the process waits until a message arrives to satisfy the dequeue or until the dequeue 
wait time-out expires. If branch or indicator options are specified, the process is not placed in the 
dequeue wait state and either the control flow is altered according to the branch options, or indicator 
values are set based on the presence or absence of a message to be dequeued. 


lf operand 3 is a system pointer, the message is dequeued from the queue specified by operand 3. If 
operand 3 is a space pointer, the message is dequeued from the queue which is specified in the tem- 
plate pointed to by the space pointer. The format of this template is given later in this section. The 
criteria for message selection are given in the message prefix specified by operand 1. The message 
text is returned in the space specified by operand 2, and the message prefix is returned in the scalar 
specified by operand 1. Improper alignment results in an exception being signaled. The format of the 
message prefix is as follows: 


e Timestamp of enqueue of message Char(8)** 


e Dequeue wait time-out value Char(8)* 
(ignored if branch options specified) 


e Size of message dequeued | Bin(4)** 
(The maximum allowable size of a queue message is 65 000 bytes.) 


e Access state modification option indicator and Char(1)* 
message selection criteria 


— Access state modification option when Bit O* 
entering Dequeue wait 


0 = Access state is not modified 
1 = Access state is modified 


— Access state modification option when Bit 1* 
leaving Dequeue wait 


O = Access state is not modified 
1 = Access state is modified 


— Multiprogramming level option Bit 2* 
0 = Leave current MPL set at Dequeue wait 
1 = Remain in current MPL set at Dequeue wait 
— Time-out option Bit 3* 
0 = Wait for specified time, then signal time-out exception 
1 = Wait indefinitely 
— Actual key to input key relationship Bits 4-7" 


(for keyed queue) 


0010: Greater than 

0100: Less than 

0110: Not equal 

1000: Equal 

1010: Greater than or equal 
1100: Less than or equal 
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¢ Search key (ignored for FIFO/LIFO queues Char(key 
but must be present for FIFO/LIFO length)” 
queues with nonzero key length values) J 
« Message key Char(key 
length)** 


Note: Fields shown here with one asterisk indicate input to the instruction, and fields shown here with 
two asterisks are returned by the machine. 


A nonzero dequeue wait time-out value overrides any dequeue wait time-out value specified as the 
current process attribute. A zero dequeue wait time-out value causes the wait time-out value to be 
taken from the current process attribute. If all wait time-out values are 0 (from the Dequeue instruction 
and the current process attribute), an immediate wait time-out (hex 3A01) exception is signaled. The 
bits in this field are numbered from 0 to 63, and bit 41 is defined as 1024 microseconds. The maximum 
dequeue wait time-out interval allowed is a value equal to (248 - 1) microseconds. Any value that indi- 
cates more time than the maximum wait time-out causes the maximum wait time-out to be used. 


The size of the message dequeued is returned in the message prefix. The size of the message 
dequeued can be less than or equal to the maximum size of message specified when the queue was 
created. When dequeuing from a keyed queue, the length of the search key field and the length of the 
message key field (in the message key prefix specified in operand 1) are determined implicitly by the 
attributes of the queue being accessed. If the message text on the queue contains pointers, the 
message text operand must be 16-byte aligned. 


The access state of the process access group is modified when a Dequeue instruction results in a wait 
and the following conditions exist: 


e The process’ instruction wait initiation access state control attribute specifies allow access state 4 
modification J 


« The dequeue access state modification option specifies modify access state 


e The multiprogramming level option specifies eave MPL set during wait. 


The process will remain in the current MPL set for a maximum of two seconds when a Dequeue 
instruction results in a wait if the multiprogramming level option specifies remain in current MPL set at 
Dequeue wait and the access state modification when entering Dequeue wait option specifies do not 
modify access state. After two seconds, the process will automatically be removed from the current 
MPL set. The automatic removal does not change or affect the total wait time specified for the process 
by the Dequeue wait time-out value. 


Operand 3 can be a system pointer or a space pointer. If it is a system pointer, this pointer will be 
addressing the queue from which the message is to be dequeued. [/f it is a space pointer, this pointer 
will be addressing a tempiate which will contain the system pointer to the queue as well as the 
Dequeue template extension. The template is 32 bytes in length and must be aligned on a 16-byte 
boundary with the format as follows: 


e Queue System pointer 
e Dequeue template extension Char(16) 
— Extension Options Char(1) 
- Modify process event mask option Bit O * 
0 = Do not modify process event mask 
1 = Modify process event mask 2 } 
- Reserved (binary 0) Bits 1-7 
— Extension Area Char(15) 


Chapter 12. Queue Management Instructions 12-5 


c 


Dequeue (DEQ) 


- New process event mask Bin(2) * 
- Previous process event mask Bin(2) ** 
- Reserved (binary 0) Char(11) 


The previous process event mask is only returned when the modify process event mask option has 
been set to 1. 


Note: Fields shown here with one asterisk indicate input to the instruction, and fields shown here with 
two asterisks are returned by the machine. 


The modify process event mask option controls the state of the event mask in the process executing 
this instruction. If the modify process event mask field specified to modify the process event mask, the 
process event mask will be changed as specified by the new process event mask field. When the 
process event mask is changed, the current process event mask will be returned in the previous 


process event mask field. 


If the system security level machine attribute is hex 40 or greater and the process is running in user 
state, then the modify process event mask option is not allowed and a template value invalid (hex 3801) 
exception is signalled. 


If the process event mask is in the masked state, the machine does not schedule signaled event moni- 
tors in the process. The event monitors continue to be signaled by the machine or other processes. 
When the process is modified to the unmasked state, event handlers are scheduled to handle those 
events that occurred while the process was masked and those events occurring while in the unmasked 
state. The number of signals retained while the process is masked is specified by the attributes of the 
event monitor associated with the process. 


The process is automatically masked by the machine when event handlers are invoked. If the process 
is unmasked in the event handler, other events can be handled if another enabled event monitor within 
that process is signaled. If the process is masked when it exits from the event handler, the machine 
explicitly unmasks the process. 

Valid masking values are: 

QO # Masked 

256 Unmasked 


Other values are reserved and must not be specified. If any other values are specified, a template 
value invalid (hex 3801) exception is signaled. 


Whether masking or unmasking the current process, the new mask takes effect upon completion of a 
satisfied dequeue. 
Resultant Conditions 

e Equal - message dequeued 


e Not equal - message not dequeued 


Authorization Required 
e Retrieve 
— Operand 3 


— Contexts referenced for address resolution 
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Lock Enforcement 
« Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x K KK 
x KK K 
x KK OK 


08 Argument/parameter 


01 parameter reference violation X X X 


0A Authorization 
01 unauthorized for operation X X 


10 Damage encountered 


04 system object damage state X | X X X 


x 


05 authority verification terminated due to damaged object 


44 partial system object damage X X X X 


1A Lock state 
01 invalid lock state xX xX 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check xX 


22 Object access 
01 object not found X X 
02 object destroyed 
03 object suspended X X X 


07 authority verification terminated due to destroyed object X 


»< 
x 
x 


08 object compressed X 


24 Pointer specification 


01 pointer does not exist X X X 


< 
>< 
>< 


02 pointer type invalid 


03 pointer address invalid object X 


2E Resource control limit 


01 user profile storage limit exceeded X 


Chapter 12. Queue Management Instructions 


12-7 


2 


Exception 
32 Scalar specification 


03 scalar value invalid 


36 Space management 


01 space extension/truncation 


3A Wait time-out 
01 dequeue 


Dequeue (DEQ) 


Operands 
1 2 3 Other 


X 
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Enqueue (ENQ) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 J 
036B Queue Message prefix Message text 


Operand ?: System pointer. 
Operand 2: Character scalar. 


Operand 3: Space pointer. 


ILE access 
ENQ ( 


var queue : system pointer; 
var message prefix : aggregate; 
message text : space pointer 


Description: A message is enqueued according to the queue type attribute specified during the 
queue’s creation. 


If keyed sequence is specified, enqueued messages are sequenced in ascending binary collating order 
according to the key value. If a message to be enqueued has a key value equal to an existing 
enqueued key value, the message being added is enqueued following the existing message. 


If the queue was defined with either /ast in, first out (LIFO) or first in, first out (FIFO) sequencing, then 
enqueued messages are ordered chronologically with the latest enqueued message being either first 
on the queue or last on the queue, respectively. A key can be provided and associated with messages 
enqueued in a LIFO or FIFO queue; however, the key does not establish a message’s position in the 
queue. The key can contain pointers, but the pointers are not considered to be pointers when they are 
placed on the queue by an Enqueue instruction. 


Operand 1 specifies the queue to which a message is to be enqueued. Operand 2 specifies the 
message prefix, and operand 3 specifies the message text. 


The format of the message prefix is as follows: 


« Size of message to be enqueued Bin(4) 
e Enqueue key value (Ignored for FIFO/LIFO Char(key 
queues with key lengths equal to 0. length) 


The size of the message to be enqueued is supplied to inform the machine of the number of bytes in 
the space that are to be considered message text. The size of the message is then considered the 
lesser of the size of the message to be enqueued attribute and the maximum message size specified on 
queue creation. The message text can contain pointers. When pointers are in message text, the 
Operand 3 space pointer must be 16-byte aligned. Improper alignment will result in an exception being 
signaled. 


If the enqueued message causes the number of messages to exceed the maximum number of mes- 
sages attribute of the queue, one of the following occurs: 


¢ If the queue is not extendable, the queue message limit exceeded (hex 2602) exception and the oY 
queue message limit exceeded (hex 0012,03,01) event are signaled. The message is not enqueued. 
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¢ If the queue !s extendable, the queue is implicitly extended by the extension value attribute. The 
message is enqueued. No exception is signaled, but the queue extended (hex 0012,04.01) event is 
signaled. 


The maximum allowable queue size, including all messages currently enqueued and the machine over- 
head, is 16 megabytes. 


Authorization Required 


« Insert 
— Operand 1 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KK 
x KK OK 
x KM KK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


0A Authorization 


01 unauthorized for operation X X 


10 Damage encountered 
04 system object damage state X X X X 
05 authority verification terminated due to damaged object X 


44 partial system object damage X X X X 


1A Lock state 
01 invalid lock state 4 X 


ic Machine-dependent exception 
03 machine storage limit exceeded X X 


04 object storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
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Exception 


24 


26 


2E 


36 


01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer address invalid object 


Process management 


02 queue message limit exceeded 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Enqueue (ENQ) 


Operands 
1 2 3 Other 
x X x 
X X X 
X X X 
X 
X 
X X X 
X X X 
X 
X 
X 
X 
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Materialize Queue Attributes (MATQAT) 


Op Code (Hex) 
0336 


Operand 2 
Queue 


Operand 1 
Receiver 


Operand 1: Space pointer. 


Operand 2: System pointer. 


ILE access 
MATQAT ( 
receiver : space pointer; 
var queue : system pointer 


Materialize Queue Attributes (MATQAT) 


Description: The attributes of the queue specified by operand 2 are materialized into the object speci- 
fied by operand 1. The format of the materialized queue attributes must be aligned on a 16-byte mul- 
tiple. The format is as follows: 


Materialization size specification 

— Number of bytes provided for materialization 
— Number of bytes available for materialization 
Object identification 

— Qbject type 

— Object subtype 

— Object name 

Object creation options 

— Existence attributes 


0 = Temporary 
1 = Permanent 


— Space attribute 


0 = Fixed-length 
1 = Variable-length 


— Initial context 


0 = Addressability not in context 
1 = Addressability in context 


— Access group 


0 = Not a member of access group 
1 = Member of access group 


— Reserved (binary 0) 
— Initialize space 
— Reserved (binary 0) 
Reserved (binary 0) 


Size of space 


Char(8) 
Bin(4) 

’ Bin(4) 
Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(4) 
Bit 0 


Bit 1 


Bit 2 


Bit 3 


Bits 4-12 

Bit 13 

Bits 14-31 

Char(4) 

Bin(4) 

12-12 
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e Initial value of space Char(1) 
e Performance class Char(4) J 
— Space alignment Bit O 


= The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, this value must 
be specified for the performance class. 
1 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space as well as to allow proper alignment of input/output 
buffers at 512-byte alignments within the the space. 


— Reserved (binary 0) Bits 1-4 
— Main storage pool selection Bit 5 


O = Process default main storage pool is used for object. 
1 = Machine default main storage pool is used for object. 


— Reserved (binary 0) Bit 6 


— Block transfer on implicit Bit 7 
access state modification 


OQ = Transfer the minimum storage transfer size for this object. This value is 1 storage unit. 
= Transfer the machine default storage transfer size. This value is 8 storage units. 


— Reserved (binary 0) Bits 8-31 
¢ Reserved (binary 0) ’ Char(7) 
¢ Context System pointer : 
¢ Access group System pointer 2) 
¢ Queue attributes Char(‘) 
— Message content Bit 0 


0 = Contains scalar data only 


1 = Contains pointers and scalar data 
— Queue type Bits 1-2 
00 = Keyed 
01 = Last in, first out 
10 = First in, first out 
— Queue overflow action Bit 3 


0 = Signal exception 


1 Extend queue 
— Reserved (binary 0) Bits 4-7 
e Current maximum number of messages Bin(4) 
¢ Current number of messages enqueued Bin(4) 
¢ Extension value Bin(4) 
« Key length Bin(2) 
¢ Maximum size of message to be enqueued Bin(4) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 2) 


of less than 8 causes the materialization length (hex 3803) exception. 
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The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception described previously) are signaled when the receiver contains insufficient 
area for the materialization. 


See the Create Queue (CRTQ) instruction for a description of these fields. 


Authorization Required 
¢« Operational! 

— Operand 2 
¢« Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
0A Authorization 

01 unauthorized for operation X X 
10 Damage encountered 

04 system object damage state X X X 

05 authority verification terminated due to damaged object X 

44 partial system object damage X X X 
1A Lock state 

01 invalid lock state X X 
20 Machine support 

02 machine check X 

03 function check X 
22 Object access 

01 object not found X X 
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Exception 


24 


2E 


36 


38 


02 object destroyed 
03 object suspended 
07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer address invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 
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Materialize Queue Messages (MATQMSG) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
033B Receiver Queue Message selection 
template 


Operand 7: Space pointer. 
Operand 2: System pointer. 


Operand 3: Character(16) scalar (fixed length). 


ILE access 
MATQMSG ( 
receiver : space pointer; 
var queue : system pointer; 


var selection template =: aggregate 


Description: This instruction materializes selected messages on a queue. One or more messages on 
the queue specified by operand 2 is selected according to information provided in operand 3 and mate- 
rialized into operand 1. The number of messages materialized and the amount of key and message 
text data materialized for each message is governed by the message selection template. 


Note that the list of messages on a queue is a dynamic attribute and may be changing on a continual 
basis. The materialization of messages provided by this instruction is just a picture of the status of the 
queue at the point of interrogation by this instruction. As such, the actual status of the queue may 
differ from that described in the materialization when subsequent instructions use the information in 
the template as a basis for operations against the queue. 


Operand 1 specifies a space that is to receive the materialized attribute values. 
Operand 2 is a system pointer identifying the queue from which the messages are to be materialized. 
Operand 3 is a character (16) scalar specifying which messages are to be materialized. 


The operand 1 space pointer must address a 16-byte boundary. The materialization template has the 
following format: 


e Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

° Materialization data Char(4) 
— Count of messages materialized Bin(4) 

* Queue data Char(12) 
— Count of messages on the queue Bin(4) 
— Maximum message size Bin(4) 
— Key size Bin(4) 

* Reserved Char(8) 

* Message data (repeated for each message) Char(*) 


12-16 
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¢ Message attributes Char(16) 
— Message enqueue time Char(8) 
— Message length Bin(4) 
— Reserved Char(4) 

e Message key Char(*) 

e Message text Char(*) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions are signaled in the event that the 
receiver contains insufficient area for the materialization, other than the materialization length (hex 
3803) exception described previously. 


The maximum message size and key size are values specified when the queue was created. If the 
queue is not a keyed queue, the value materialized for the key size is zero. 


The length of the message key and message text fields is determined by values supplied in operand 3, 
message selection data. If the length supplied in operand 3 exceeds the actual data length, the 
remaining space will be padded with binary zeros. 


The message selection template identified by operand 3 must be at least 16 bytes and must be ona 
16-byte boundary. The format of the message selection template is as follows: 


e Message selection Char(2) 
— Type Bits 0-3 
0001 = All messages 
0010 = First 
0100 = Last 
1000 = Keyed 
All other values are reserved 
— Key relationship (if needed) Bits 4-7 
0010 = Greater than 
0100 = Less than 
0110 = Not equal 
1000 = Equal 
1010 = Greater than or equal 
1100 = Less than or equal 
All other values are reserved 
— Reserved Bits 8-15 
¢ Lengths Char(8) 
— Number of key bytes to materialize Bin(4) 
— Number of message text bytes to materialize Bin(4) 
e Reserved Char(6) 
e Key (if needed) Char(*) 
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The message selection type must not specify keyed if the queue was not created as a keyed queue. 


Both of the fields specified under lengths must be zero or an integer multiple of 16. The maximum 
value allowed for the key length is 256. The maximum value allowed for the message text is 65536. 


Authorization Required 
e Retrieve 
— Operand 2 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialization 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 

Operands 
Exception 1 2 3 4 Other 
06 Addressing 


01 space addressing violation 
02 boundary alignment 


03 range 


x KK RK 
x KK KW 
x K K KM 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage state X X 


x< 


05 authority verification terminated due to damaged object 


44 partial system object damage X 


1A Lock state 


01 invalid lock state 4 


20 Machine support 
02 machine check ».4 


03 function check X 


22 Object access 
01 object not found xX X » 4 
02 object destroyed 
03 object suspended > 4 X X 


07 authority verification terminated due to destroyed object X 


x< 
~*~ 
x 


08 object compressed Xx 


Chapter 12. Queue Management Instructions 


12-18 


Materialize Queue Messages (MATQMSG) 


Operands 

Exception 1 2 3 4 Other 
24 Pointer specification 

01 pointer does not exist X X X 

02 pointer type invalid X X X 

03 pointer address invalid object X 
28 Process state 

02 process control space not associated with a process X 
2E Resource control limit 

01 user profile storage limit exceeded X 
32 Scalar specification 

01 scalar type invalid X X X 

02 scalar attributes invalid X xX X 

03 scalar value invalid X 
36 Space management 

01 space extension/truncation X 
38 Template specification 

03 materialization length exception X 
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Chapter 13. Object Lock Management Instructions 


This chapter describes the lock management instructions. The instructions are in alphabetic order. 
For an alphabetic summary of all the instructions, see Appendix A, “Instruction Summary.” 


LOCK ODIGCCLCEOCI): ns iene Bh et ee seems lg actin een etd Sones hore et ae ee tO 13-3 
Lock Space Location (LOCKSL) ........0.. 0... 0. eee ee ee ee 13-8 
Materialize Data Space Record Locks (MATDRECL) ...........0.........0 0.008. 13-13 
Materialize Process Locks (MATPRLK) ..........0. 2.00000 eee ee ee ee eee 13-17 
Materialize Process Record Locks (MATPRECL) .............. 0.00002 eee eee 13-20 
Materialize Selected Locks (MATSELLK) .........0... 0.0... 2... eee eee ee ees 13-24 
Transfer: Object Lock (MPREOCK): 2 dca. 2ueu db veo e ee eee ho SR Sea AER HAR 13-27 
Unlock: Objecl(UNEOCK). “4caas ea eied ocean ee Ra Saline ELAbe SEs ESE AEE 13-30 
Unlock Space Location (UNLOCKSL) .........2..0 02000000000 eee ee eee 13-33 
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Lock Object (LOCK) 


Op Code (Hex) Operand 1 
O3F5 Lock request tem- 
plate 


Operand 7: Space pointer. 


ILE access 


LOCK ( 
lock_request_template : space pointer 
) 


Description: The instruction requests that locks for system objects identified by system pointers in the 
space object (operand 1) be allocated to the issuing process. The lock state desired for each object is 
specified by a value associated with each system pointer in the lock template (operand 1). 


The lock request template must be aligned on a 16-byte boundary. The format is as follows: 


e Number of lock requests in template Bin(4) 
e Offset to lock state selection values Bin(2) 
¢ Wait time-out value for instruction ' Char(8) 
e Lock request options Char(1) 
— Lock request type Bits 0-1 


00 = Immediate request- If all locks cannot be immediately granted, signal /ock request not 
grantable (hex 1A02) exception. 


01 = Synchronous request- Wait until all locks can be granted. 
10 = Asynchronous request- Allow processing to continue and signal event when the object is 
available. 
— Access state modifications Bits 2-3 
- When the process is entering Bit 2 
lock wait for synchronous request: 
O= Access state should not be modified. 
1= Access state should be modified. 
- When the process is leaving lock wait: Bit 3 
O= Access state should not be modified. 
1= Access state should be modified. 
— Reserved (binary 0) Bits 4-5* 
— Time-out option Bit 6 


O= Wait for specified time, then signal time-out exception. 
1= Wait indefinitely. 


— Template extension specified Bit 7 


O= Template is not specified. 
1= Template is specified. 


e Reserved (binary 0) Char(1) 
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The Lock Object template extension is only present if template extension specified is indicated above. 
Otherwise. the Object(s) to be locked should immediately follow. 


¢ Lock Object template extension Char(16) ~~ 
— Extension options Char(‘) 
- Modify process event mask option Bit 0 


O = Do not modify process event mask 
1 = Modify process event mask 


- Reserved (binary 0) Bits 1-7 
— Extension area Char(15) 
- New process event mask UBin(2) 
- Previous process event mask UBin(2) 
- Reserved (binary 0) Char(11) 
e Object(s) to be locked System pointer 


This should be repeated as specified by number of lock requests in template above. 


The lock state selection is located by adding the offset to lock state selection values above to operand 
1. 


e Lock state selection Char(1) 
(repeated for each pointer in the template) 
— Requested lock state Bits 0-4 


(1 = lock requested, 0 = lock not requested) 


ir 


Only one state may be requested. 


- LSRD lock Bit 0 

- LSRO lock Bit 1 

- LSUP lock Bit 2 

- LEAR lock Bit 3 

- LENR lock Bit 4 
— Reserved (binary 0) Bits 5-6* 
— Entry active indicator Bit 7 


O = Entry not active - This entry is not used. 
1 = Entry active - Obtain this lock. 
Note: Entries indicated with an asterisk are ignored by the instruction. 


Lock Allocation Procedure: A single Lock instruction can request the allocation of one or more lock 
states on one or more objects. Locks are allocated sequentially until all locks requested are allocated. 


The offset to lock state selection vaiues specifies an offset from the beginning of the lock request. This 
offset is used to locate the lock state selection values. 


The wait time-out field establishes the maximum amount of time that a process competes for the 

requested set of locks when either lock request type is either synchronous or asynchronous. The bits 

in this field are numbered from O to 63, and bit 41 is defined as 1024 microseconds. The maximum wait 

time-out interval allowed is a value equal to (248 - 1) microseconds. Any value that indicates more time 

than the maximum wait time-out causes the maximum wait time-out to be used. If the wait time-out 

field is specified with a value of binary 0, then the value associated with the default wait time-out field J 
in the process definition template establishes the time interval. 
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When a requested lock state cannot be immediately granted. any locks already allocated by this Lock 
instruction are released, and the lock request type specified in the lock request template establishes 
the machine action. The lock request types are described in the following paragraphs. 


* Immediate Request- lf the requested locks cannot be granted immediately, this option causes the 
lock request not grantable (hex 1A02) exception to be signaled. No locks are granted and the lock 
request is canceled. 


¢ Synchronous Request- This option causes the process requesting the locks to be placed in the wait 
State until all requested locks can be granted. If the locks cannot be granted in the time interval 
established by the wait time-out field specified in the lock request template, the /ock wait time-out 
(hex 3A02) exception is signaled to the requesting process at the end of the interval. No locks are 
granted, and the lock request is canceled. 


e Asynchronous Request- This option allows the requesting process to proceed with execution while 
the machine asynchronously attempts to satisfy the lock request. 


When the synchronous request option is specified and the requested locks cannot be immediately allo- 
cated, the access state modification field in the lock request template specifies whether the access 
state of the process access group is to be modified on entering and/or returning from the lock wait. 
The field has no effect if the process instruction wait access state control attribute specifies that no 
access state modification is allowed. If the process attribute value specifies that access state modifica- 
tion is allowed and the wait on event access state modification option specifies modify access state, 
the machine modifies the access state for the specified process access group. 


If the lock request type is synchronous and the invocation containing the lock instruction is terminated, 
then the lock request is canceled. 


If the lock request is satisfied, then the object locked (hex 000A,01,01) event is signaled to the 
requesting process. If the request is not satisfied in the time interval established by the wait time-out 
field specified in the lock request template, the asyncronous lock wait timeout (hex 000A,04,01) event is 
signaled to the requesting process. No locks are granted, and the lock request is canceled. If an 
object is destroyed while a process has a pending request to lock the object, the object destroyed (hex 
000A,02,01) event is signaled to the waiting process. 


If the lock request type is asynchronous and the invocation containing the Lock instruction is termi- 
nated, then the lock request remains active. 


When two or more processes are competing for a conflicting lock allocation on a system object, the 
machine attempts to first satisfy the lock allocation request of the process with the highest priority. 
Within that priority, the machine attempts to satisfy the request that has been waiting longest. 


lf any exception is identified during the instruction’s execution, any locks already granted by the 
instruction are released, and the lock request is canceled. 


For each system object lock, counts are kept by lock state and by process. When a lock request is 
granted, the appropriate lock count(s) of each lock state specified is incremented by 1. 


If a previously unsatisfied lock request is satisfied by the transfer of a lock from another process, the 
lock request and transfer lock are treated as independent events relative to lock accounting. The 
appropriate lock counts are incremented for both the lock request and the transfer lock function. 


The modify process event mask option controls the state of the event mask in the process executing 
this instruction. If the event mask is in the masked state, the machine does not schedule signaled 
event monitors in the process. The event monitors continue to be signaled by the machine or other 
processes. When the process is modified to the unmasked state, event handlers are scheduled to 
handle those events that occurred while the process was masked and those events occurring while in 
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the unmasked state. The number of events retained while the process is masked is specified by the 
attributes of the event monitor associated with the process. 


A lock request with an asynchronous lock request type cannot have the modify process event mask 
option set to 1. 


If the system security level machine attribute is hex 40 or greater and the process is running in user 
state, then the modify process event mask option is not allowed and a template value invalid (hex 3801) 
exception is signalled. 


When the modify process event mask is set to 1, the previous process event mask will be returned and 
the new process event mask will take effect only when the lock(s) have been successfully granted. If 
the lock request is not successful, the previous process event mask value is not returned, nor does the 
new process event mask take effect. 


The process is automatically masked by the machine when event handlers are invoked. If the process 
is Unmasked in the event handler, other events can be handled if another enabled event monitor within 
that process is signaled. lf the process is masked when it exits from the event handler, the machine 
explicitly unmasks the process. 

Valid masking values are: 

QO Masked 

256 Unmasked 


Other values are reserved and must not be specified. If any other values are specified, a template 
value invalid (hex 3801) exception is signaled. 


Whether masking or unmasking the current process, the new mask takes effect upon completion of a 
satisfied lock object. 


Authorization Required 
e Some authority or ownership 
— Objects to be locked 
* Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 Other 
06 Addressing 
01 space addressing violation X 
02 boundary alignment Xx 
03 range X 
X 


06 optimized addressability invalid 


08 Argument/parameter 
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* 


J 


Exception 


0A 


1A 


1C 


20 


22 


24 


2E 


36 


38 


3A 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 
01 invalid lock state 


02 lock request not grantable 


Machine-dependent exception 
03 machine storage limit exceeded 
06 machine lock limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Wait time-out 
02 lock 
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Operands 
1 
X 
X 
X X 
X 
X X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 


Other 
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Lock Space Location (LOCKSL) 


Op Code (Hex) Operand 1 Operand 2 
O3F6 Space location or Lock request 
Lock Request 
Template 


Operand 1: Space pointer data object. 


Operand 2: Char(1) scalar or null. 


ILE access 
LOCKSL ( 
var space _location : space pointer; 
var lock_request : aggregate OR 


null operand 


) 


Description: When operand 2 is not null, the space location (operand 1) is granted to the issuing 
process according to the lock request specified by operand 2. When operand 2 is null, the instruction 
requests that the space locations identified in the lock request template (operand 1) be granted to the 
issuing process. 


Locking a space location does not prevent any byte operation from referencing that location, nor does 
it prevent the space from being extended, truncated, or destroyed. Space location locks follow the 
normal locking rules with respect to conflicts and waits but are strictly symbolic in nature. 


A space pointer machine object cannot be specified for operand 1. 
The following is the format of operand 2 when not null: 


e Lock request Char(1) 


— Lock state selection Bits 0-4 
(1 = lock requested, 0 = lock not requested) 


Only one state may be requested. 


- LSRD lock Bit 0 
- LSRO lock Bit 1 
- LSUP lock Bit 2 
- LEAR lock Bit 3 
- LENR lock Bit 4 
— Reserved (binary Q) Bits 5-7 


For this form, if the requested lock cannot be immediately granted, the process will enter a synchro- 
nous wait for the lock for a period of up to the interval specified by the process default time-out value. 
If the wait exceeds this time limit, a space location lock wait exception is signaled, and the requested 
lock is not granted. 


During the wait, the process access state may be modified. This can occur if the process’ jnstruction 
wait access state control attribute is set to allow access state modification. 


When operand 2 is null, the lock request template identified by operand 1 must be aligned on a 16-byte 
boundary. The format of operand 1 is as follows: 
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Number of space location lock requests 
in template 


Offset to lock state selection values 
Wait time-out value for instruction 
Lock request options 

— Reserved (binary 0) 

— Lock request type 


0 = Immediate request-if all locks cannot be 
immediately granted, signal exception. 

1 = Synchronous request-Wait until all locks 
can be granted. 


— Access state modifications 


- When the process is entering 
lock wait for synchronous request: 


O= Access state should not be modified. 
1= Access state should be modified. 


- When the process is leaving lock wait: 


O= Access state should 
not be modified. 

1= Access state should 
be modified. 


— Reserved (binary 0) 
— Time-out option 


O= Wait for specified time, 
then signal time-out exception. 
1= Wait indefinitely. 


— Reserved (binary 0) 
— Modify process event mask option 


0 
1 


— Reserved (binary 0) 


Do not modify process event mask 
Modify process event mask 


Modify process event mask control 
— New process event mask 

— Previous process event mask 
Reserved (binary 0) 


Space location(s) to be locked 


This should be repeated as specified by number of lock requests in template above. 


Bin(4) 


Bin(2) 
Char(8) 
Char(3) 
Bit O 
Bit 1 


Bits 2-3 
Bit 2 


Bit 3 


Bits 4-5 
Bit 6 


Bits 7-15 
Bit 16 


Bits 17-23 
Char(4) 
UBin(2) 
UBin(2) 
Char(11) 


Lock Space Location (LOCKSL) 


Space pointer data object 


The lock state selection is located by adding the offset to lock state selection values above to operand 


1; 


Lock state selection 
(repeated for each pointer in the template) 


— Requested lock state 


Char(1) 


Bits 0-4 
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(1 = lock requested, 0 = lock not requested) 


Only one state may be requested. 
- LSRD lock Bit 0 J 
- LSRO lock Bit 1 
- LSUP lock Bit 2 
- LEAR lock Bit 3 
- LENR lock Bit 4 
— Reserved (binary 0) Bit 5-6 
— Entry active indicator Bit 7 


0 = Entry not active- This entry is not used. 
1 = Entry active- Obtain this lock. 


Lock Allocation Procedure: A single Lock Space Location instruction can request the allocation of one 
or more lock states on one or more space locations. Space location locks are granted sequentially 
until all the locks requested are granted. 


The wait time-out field establishes the maximum amount of time that a process competes for the 
requested set of locks when the /ock request type is synchronous. The bits in this field are numbered 
from 0 to 63, and bit 41 is defined as 1024 microseconds. The maximum wait time-out interval allowed 
is a value equal to (248 - 1) microseconds. Any value that indicates more time than the maximum wait 
time-out causes the maximum wait time-out to be used. If the wait time-out field is specified with a 
value of binary 0, then the value associated with the default wait time-out parameter in the process 
definition template establishes the time interval. 


When a requested lock state cannot be immediately granted, any locks already granted by this Lock - 
Space Location instruction are released, and the /ock request type specified in the lock request tem- J 
plate establishes the machine action. The lock request type values are described in the following par- 

agraphs. 


e Immediate Request- |f the requested space location locks cannot be granted immediately, this 
option causes the /ock request not grantable (hex 1AQ2) exception to be signaled. No space 
location locks are granted, and the jock request is canceled. 


e Synchronous Request- This option causes the process requesting the locks to be placed in the wait 
state until all requested locks can be granted. If the locks cannot be granted in the time interval 
established by the wait time-out field specified in the lock request template, the space location lock 
wait time-out (hex 3A04) exception is signaled to the requesting process at the end of the interval. 
No locks are granted, and the lock request is canceled. 


If the Jock request type is synchronous and the requested locks cannot be immediately granted, the 
access state modification field in the lock request template specifies whether the access state of the 
process access group is to be modified on entering and/or returning from the lock wait. The param- 
eter has no effect if the process instruction wait access state control attribute specifies that no access 
state modification is allowed. If the process attribute value specifies that access state modification is 
allowed and the wait on event access state modification option specifies modify access state, the 
machine modifies the access state for the specified process access group. 


If the Jock request type is synchronous and the invocation containing the Lock Space Location instruc- 
tion is terminated, then the lock request is canceled. 


The modify process event mask option controls the state of the event mask in the process executing 

this instruction. When the process event mask is in the masked state, the machine does not schedule 

signaled event monitors in the process. The event monitors continue to be signaled by the machine or 2) 
other processes. When the process event mask is modified to the unmasked state, event handlers are 
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scheduled to handle those events that occurred while the process was masked and those events 
occurring while in the unmasked state. 


If the system security level machine attribute is hex 40 or greater and the process is running in user 
State. then the modify process event mask option is not allowed and a template value invalid (hex 3801) 
exception is signalled. 


When the modify process event mask is set to 1, the previous process event mask will be returned and 
the new process event mask will take effect only when the space location lock(s) have been success- 
fully granted. If the space location lock request is not successful, the previous process event mask 
value is not returned, nor does the new process event mask take effect. 


The process event mask values are validity checked only when the modify process event mask is set 
to 1, and ignored otherwise. Valid masking values are: 

Q Masked 

256 Unmasked 


Other values are reserved and must not be specified, otherwise a template value invalid (hex 3801) 
exception is signaled. 


If any exception is identified during the instruction’s execution, any locks already granted by the 
instruction are released, and the lock request is canceled. 


For each space location lock, counts are kept by lock state and by process. When a lock request is 
granted, the appropriate /ock- count of each lock state specified is incremented by 1. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
10 Damage encountered 

04 system object damage state X 

44 partial system object damage X 
1A Lock state 

02 lock request not grantable X 
1c Machine-dependent exception 

03 machine storage limit exceeded X 

06 machine lock limit exceeded X 
20 Machine support 

02 machine check X 

03 function check X 
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Operands 
Exception 1 2 Other 


22 Object access . ) 


02 object destroyed X X 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X X 


02 pointer type invalid X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 scalar type invalid xX x 


03 scalar value invalid xX 


36 Space management 


01 space extension/truncation xX 


38 Template specification 


01 template value invalid xX 


3A Wait time-out 


04 space location lock wait X 


C 
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Materialize Data Space Record Locks (MATDRECL) 


Op Code (Hex) Operand 1 Operand 2 
O32E Receiver Record selection 
template 


Operand 1: Space pointer. 


Operand 2: Space pointer. 


ILE access 


MATDRECL ( 
receiver : space pointer; 
selection template : space pointer 


Description: This instruction materializes the current allocated locks on the specified data space 
record. 


The current lock status of the data space record identified by the template in operand 2 is materialized 
into the space identified by operand 1. 


The record selection template identified by operand 2 must be 16-byte aligned. The format of the 
record selection template is as follows. 


e Record selection Char(24) 
— Data space identification System pointer 
— Record number Bin(4) 
— Reserved Char(4) 
e Lock selection Char(8) 
— Materialize data space locks held Bit 0 


1 = Materialize 
0 = Do not materialize 


— Materialize data space locks waited for Bit 1 

1 = Materialize 

0 = Do not materialize 
— Reserved Bits 2-7 
— Reserved Char(7) 


The data space identification must be a system pointer to a data space. 


The record number is a relative record number within that data space. If the record number is zero 
then all locks on the specified data space will be materialized. If the record number is not valid for the 
specified data space a template value invalid (hex 3801) exception is signaled. 


Both of the fields specified under lock selection are bits which determine the locks to be materialized. 
lf the materialize data space locks held is materialize, the current holders of the specified data space 
record lock are materialized. If the materialize data space locks waited for is materialize, any process 
waiting to lock the specified data space record is materialized. 
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The materialization template identified by operand 1 must be 16-byte aligned. The format of the 
materialization is as follows: 


e Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Materialization data Char(8) 
— Count of locks held UBin(2) 
— Count of locks waited for UBin(2) 
— Reserved Char(4) 

¢ Locks held identification Char(32) 


(repeated for each lock held) 


— Process control space 


System pointer 


— Record number Bin(4) 
— Lock state being described Char(‘1) 
Hex CO = DLRD lock state 
Hex F8 = DLUP lock state 
All other values are reserved. 
— Reserved , Char(11) 
e Locks waited for identification Char(32) 


(repeated for each lock waited for) 


— Process control space 


system pointer 


— Record number Bin(4) 

— Lock state being described Char(1) 
Hex CO = DLRD lock state 
Hex F8 = DLUP lock state 
All other values are reserved. 

— Reserved Char(11) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 


tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 


of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, the excess bytes are unchanged. No exceptions are signaled in the event that the 
receiver contains insufficient area for the materialization, other than the materialization length excep- 
tion described previously. 


The count of locks held contains the number of locks held. One system pointer to the process control 
space (PCS) of each process holding a lock, the relative record number which is locked, and the lock 


state are materialized in the area identified as locks held identification. These fields contain data only 


if materialize data space locks held is materialize. 


The count of locks waited for contains the number of locks being waited for. One system pointer to the 
process control space (PCS) of each process waiting for a lock, the relative record number, and the 
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lock state which the process is waitng for are materialized in the area identified as locks waited for 
identification. These fields contain data only if materialize data space locks waited for is materialize. 


Authorization Required 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 


Exception 1 2 Other 
06 Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x KX KK 
x KX KK 


08 Argument/parameter 


01 parameter reference violation X X 


0A Authorization 


01 unauthorized for operation X X 


10 Damage encountered 


04 system object damage state X X 


>< 


0S authority verification terminated due to damaged object 


44 partial system object damage X 


1A Lock state 
01 invalid lock state X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check D4 


22 Object access 
01 object not found X X 
02 object destroyed 
03 object suspended X X 


07 authority verification terminated due to destroyed object X 


~< 
~< 


08 object compressed X 


24 Pointer specification 
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Operands 
Exception 1 2 Other 
01 pointer does not exist X X } 
02 pointer type invalid 4 4 
2E Resource control limit 
01 user profile storage limit exceeded X 
32 Scalar specification 
01 scalar type invalid X X 
36 Space management 
01 space extension/truncation X 
38 Template specification 
01 template value invalid X 
03 materialization length exception X 
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Operand 1 


Op Cade (Hex) Operand 2 
0312 Receiver Process control 
space 
Operand ?: Space pointer. 
Operand 2: System pointer or null. 
ILE access 
MATPRLK ( 
receiver : space pointer; 


var process contro] _spacec : system pointer OR 
null operand 


Materialize Process Locks (MATPRLK) 


Description: The lock status of the process identified by operand 2 is materialized into the receiver 
specified by operand 1. If operand 2 is null, the lock status is materialized for the process issuing the 
instruction. The materialization identifies each object or space location for which the process has a 
lock allocated or for which the process is in a synchronous or asynchronous wait. The format of the 


materialization is as follows: 
e Materialization size specification 
— Number of bytes provided for materialization 
— Number of bytes available for materialization 
e Number of lock entries 
e Expanded number of lock entries 
e Reserved (binary 0) 


e Lock status (repeated for each lock 
currently allocated or waited for by the process) 


— Object, space location, or 
binary 0 if no pointer exists 


— Lock state 
- LSRD 
- LSRO 
- LSUP 
- LEAR 
- LENR 
- Reserved (binary 0) 
— Status of lock state for process 
- Reserved 
- Object or space location no longer exists 
- Waiting because this lock is not available 


- Process in asynchronous wait for lock 


Char(8) 


Bin(4) 
Bin(4) 
Bin(2) 
Bin(4) 
Char(2) 
Char(32) 


System pointer 
or Space pointer 


Char(‘1) 
Bit 0 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bits 5-7 
Char(1) 
Bits O-1 
Bit 2 
Bit 3 
Bit 4 
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- Process in synchronous wait for lock Bit 5 

- Implicit lock (machine-applied) Bit 6 

- Lock held by process Bit 7 J 
e Reserved (binary 0) Char(14) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception described previously) are signaled if the receiver contains insufficient area 
for the materialization. 


The number of lock entries field identifies the number of lock entries that are materialized. When a 
process holds more than 32,767 locks, this field is set with its maximum value of 32,767. This field has 
been retained in the template for compatibility with programs using the template prior to the changes 
made to support materialization of more than 32,767 lock entries. 


The expanded number of lock entries field identifies the number of lock entries that are materialized. 

This field is always set in addition to the number of lock entries field described previously; however, it 

does not have a maximum limit of 32,767, so it can be used to specify that more than 32,767 locks have 

been materialized. When a process holds more than 32,767 locks, the number of lock entries field will 

equal 32,767, which would be incorrect. The expanded number of lock entries field, however, will iden- 5 
tify the correct number of lock entries materialized. In all cases, this field should be used instead of J 
the number of lock entries field to get the correct count of lock entries materialized. 


Authorization Required 
e Retrieve 


— Context referenced by address resolution 


Lock Enforcement 
« Materialize 


— Contexts referenced for address resolution 


Exceptions 

Operands 
Exception 1 2 Other 
06 Addressing 


01 space addressing violation X X 
02 boundary alignment X X 
03 range X X 
06 optimized addressability invalid Xx X 


08 Argument/parameter 
01 parameter reference violation X X 
10 Damage encountered 
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Exception 


1c 


20 


22 


24 


28 


2E 


36 


38 


04 system object damage state 
05 authority verification terminated due to damaged abject 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Process state 


02 process control space not associated with a process 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 
X X 
X X 

X 

X 
X 


Other 
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Materialize Process Record Locks (MATPRECL) 


Op Code (Hex) Operand 1 Operand 2 J 
O31E Receiver Process selection 
template 


Operand 1: Space pointer. 


Operand 2: Space pointer. 


ILE access 


MATPRECL ( 
receiver : space pointer; 
selection template : space pointer 


Description: This instruction materializes the current allocated data space record locks held by the 
process. The current lock status of the process identified in the process selection template specified 
by operand 2 is materialized into the receiver identified by operand 1. The materialization identifies 
each data space record lock which the process has or the process is waiting to obtain. 


If the process control space (PCS) pointer is null or all Zeros, the lock activity for the process issuing 
the instruction is materialized. 


The process selection template identified by operand 2 must be 16-byte aligned. The format of the i. 
process selection template is as follows: J 
e Process selection Char(16) 
— Process identification System pointer 
e Lock selection Char(8) 
— Materialize held locks Bit 0 
1 = Materialize 
QO = Do not materialize 


— Materialize locks waited for Bit 1 


1 = Materialize 
0 = Do not materialize 


— Reserved Bits 2-7 

— Reserved Char(7) 
The process identification must be a system pointer to a process control space (PCS) or null, all zeros. 
Both of the fields specified under lock selection are bits which determine the locks to be materialized. 
If the materialize held locks is materialize, any data base record lock held by the process is material- 


ized. If the materialize lock waited for is materialize any data base record lock the process is waiting 
for is materialized. 


The materialization template identified by operand 1 must be 16-byte aligned. The format of the 


materialization is as follows: )) 
¢ Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 


Chapter 13. Object Lock Management Instructions 13-20 


Materialize Process Record Locks (MATPRECL) 


— Number of bytes available for materialization Bin(4) 
¢ Materialization data Char(8) 
— Count of locks held Bin(2) 
— Count of locks waited for Bin(2) 
— Reserved Char(4) 
e Locks held identification Char(32) 
(repeated for each lock held) 
— Data space identification System pointer 
— Relative record number Bin(4) 
— Lock state being described Char(1) 


Hex CO = DLRD lock state 
Hex F8 = DLUP lock state 


All other values are reserved. 


— Reserved Char(11) 

e Locks waited for identification Char(32) 
(repeated for each lock waited for) 
— Data space identification System pointer 
— Relative record number Bin(4) 
— Lock state being described Char(1) 


Hex CO = DLRD lock state 
Hex F8 = DLUP lock state 


All other values are reserved. 
— Reserved Char(11) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, the excess bytes are unchanged. No exceptions are signaled in the event that the 
receiver contains insufficient area for the materialization, other than the materialization length (hex 
3803) exception described previously. 


The count of locks held contains the number of locks held by the process. One system pointer to the 
data space, relative record number in the data space, and lock state is materialized in the area identi- 
fied as locks held identification for each lock. These fields contain data only if materialize held locks is 
materialize. 


‘ 


The count of locks waited for contains the number of locks that the process is waiting for. One system 
pointer to the data space, relative record number in the data space, and lock state is materialized in 
the area identified as locks waited for identification for each lock waited for. These fields contain data 
only if materialize locks waited for is materialize. 
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Materialize Process Record Locks (MATPRECL) 


Authorization Required 
* Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
0A Authorization 

01 unauthorized for operation X X 
10 Damage encountered 

04 system object damage state X X 

05 authority verification terminated due to damaged object X 

44 partial system object damage X 
1A Lock state 

01 invalid lock state X 
1C Machine-dependent exception 

03 machine storage limit exceeded X 
20 Machine support 

02 machine check X 

03 function check X 
22 Object access 

01 object not found X X 

02 object destroyed X X 

03 object suspended X X 

07 authority verification terminated due to destroyed object X 

08 object compressed X 
24 Pointer specification 

01 pointer does not exist X X 

02 pointer type invalid X X 
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ART, | 


Exception 
2E Resource control limit 


01 user profile storage limit exceeded 


32 Scalar specification 


01 scalar type invalid 


36 Space management 


01 space extension/truncation 


38 Template specification 
01 template value invalid 


03 materialization length exception 


Materialize Process Record Locks (MATPRECL) 


Operands 
1 2 Other 


X 
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Materialize Selected Locks (MATSELLK) 


Op Code (Hex) Operand 1 Operand 2 
033E Receiver Object or space 
location 


Operand f: Space pointer. 


Operand 2: System pointer or space pointer data object. 


ILE access 
MATSELLK ( 


receiver : space pointer; 
var system or_space pointer : pointer 


Materialize Selected Locks (MATSELLK) 


Description: The locks held by the process issuing this instruction for the object or space location 
referenced by operand 2 are materialized into the template specified by operand 1. The format of the 


materialization template is as follows: 
e Materialization size specification 
— Number of bytes provided for materialization 
— Number of bytes available for materialization 
« Cumulative lock status for all locks on operand 2 
— Lock state 
- LSRD 
- LSRO 
- LSUP 
- LEAR 
- LENR 
— Reserved (binary 0) 
e Reserved 


¢ Number of lock entries 


e Reserved 
e Lock status (repeated for each Jock currently 
allocated) 
— Lock state 
Hex 80 = LSRD lock request 
Hex 40 = LSRO lock request 
Hex 20 = LSUP lock request 
Hex 10 = LEAR lock request 
Hex 08 = LENR lock request 


All other values are reserved 
— Status of lock 


- Reserved (binary 0) 
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Char(8) 
. Bin(4) 
Bin(4) 
Char(1) 
Char(1) 
Bit 0 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bits 5-7 
Char(‘1) 
Bin(2) 
Char(2) 
Char(2) 


Char(1) 


Char(1) 


Bits 0-5 


13-24 


Materialize Selected Locks (MATSELLK) 


- implicit lock Bit 6 


0 Not implicit lock 
1 = Is implicit lock 


- Reserved (binary 1) Bit 7 


The first 4 bytes of the materialization identifies the total number of bytes provided for use by the 
instruction. This value is supplied as input to the instruction and is not modified by the instruction. A 
value of less than 8 causes the materialization length (nex 3803) exception to be signaled. 


The second 4 bytes of the materialization identifies the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions are signaled in the event that the 
receiver contains insufficient area for the materialization, other than the materialization length (hex 
3803) exception described previously. 


A space pointer machine object cannot be specified for operand 2. 


Authorization 
e Retrieve 


— Context referenced by address resolution 


Lock Enforcement: 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation X X 
02 boundary alignment X X 
03 range X X 
06 optimized addressability invalid X X 
08 Argument/parameter 
01 parameter reference violation X X 
0A Authorization 
02 unauthorized for operation Xx 
10 Damage encountered 
04 system object X X X 
05 authority verification terminated due to damaged object X 
44 partial system object damage X 
1A Lock state 
01 invalid lock state X 
1C Machine-dependent exception 
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Materialize Selected Locks (MATSELLK) 


Exception 


20 


22 


24 


28 


2E 


32 


36 


38 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Process state 


02 process control space not associated with a process 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 

X 

X 
X X 
X 


Other 


ar akeel 
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Transfer Object Lock (XFRLOCK) 


Transfer Object Lock (XFRLOCK) 


4 Op Code (Hex) Operand 1 Operand 2 
0382 Receiving process Lock transfer tem- 
control space plate 


Operand 1: System pointer. 


Operand 2: Space pointer. 


| ILE access 

| | XFRLOCK ( 

| var receiving process control space : system pointer 
| lock_transfer_ template : space pointer 
| 


Description: The receiving process (operand 1) is allocated the locks designated in the lock transfer 
template (operand 2). Upon completion of the transfer lock request, the current process no longer 
holds the transferred lock(s). 


Operand 2 identifies the objects and the associated lock states that are to be transferred to the 
receiving process. The space contains a system pointer to each object that is to have a lock trans- 
ferred and a byte which defines whether this entry is active. If the entry is active, the space also con- 
tains the lock states to be transferred. Operand 2 must be aligned on a 16-byte boundary. The format 


is as follows: 
S e Number of lock transfer requests in template Bin(4) 
¢ Offset to lock state selection bytes Bin(2) 
e Reserved (binary 0) Char(10)* 
¢ Object lock(s) to be transferred system pointer 


This should be repeated as specified by number of lock transfer requests in template above. 


The lock state selection is located by adding the offset to lock state selection values above to operand 
1. 


¢ Lock state selection (repeated Char(1) 
for each pointer in the template) 
— Lock state to transfer. Only one Bits 0-4 
state may be requested. (1 = transfer) 
- LSRD Bit 0 
- LSRO Bit 1 
- LSUP Bit 2 
- LEAR Bit 3 
- LENR Bit 4 
— Reserved (binary 0) Bit 5* 
: — Lock count Bit 6 
S Q = The current lock count is transferred. 


1 = A lock count of 1 is transferred. 
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Transfer Object Lock (XFRLOCK) 


— Entry active indicator Bit 7 
OQ =~ Entry not active. This entry is not used. 
1 Entry active. This lock is transferred. 


Note: Entries indicated by an asterisk are ignored by the instruction. 


If the receiving process is issuing the instruction, then no operation is performed, and no exception is 
signaled. The lock count transferred is either the lock count held by the transferring process or a 
count of 1. If the receiving process already holds an identical lock, then the final lock count is the sum 
of the count originally held by the receiving process and the transferred count. 


Only locks currently allocated to the process issuing the instruction can be transferred. If the transfer 
of an allocated lock would result in the violation of the lock allocation rules, then the lock cannot be 
transferred. An implicit lock may not be transferred. 


No locks are transferred if an entry in the template is invalid. 


The locks specified by operand 2 are transferred sequentially and individually. If one lock cannot be 
transferred because the process does not hold the indicated jock on the object, then exception data is 
saved to identify the lock that could not be transferred. Processing of the next lock to be transferred 
continues. 


After all locks specified in operand 2 have been processed, the object lock transferred (hex 000A,03,01) 
event is signaled to the process receiving the locks if any locks were transferred. If any lock was not 
transferred, the invalid object lock transfer request (hex 1A04) exception is signaled. 


When an object lock is transferred, the transferring process synchronously loses the record of the lock, 
and the object is locked to the receiving process. However, the receiving process obtains the lock 
asynchronously after the instruction currently being executed is completed. If the transferring process 
holds multiple locks for the object, any lock states not transferred are retained in the process. 


Authorization Required 
¢« Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
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‘ 


J 


Exception 


0A 


1A 


ic 


20 


22 


24 


28 


2E 


36 


38 


Authorization 


01 unauthorized for operation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 
01 invalid lock state 


04 invalid object lock transfer request 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 abject compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Process state 


02 process control space not associated with a process 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


01 tempiate value invalid 


Transfer Object Lock (XFRLOCK) 


Operands 
1 2 
X 
X X 
X X 
X 
X X 
X Xx 
X X 
X X 
X X 
X 
X 
X 


Other 
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Unlock Object (UNLOCK) 


Unlock Object (UNLOCK) 


Op Code (Hex) Operand 1 
O3F 1 Unlock template 


Operand 1: Space pointer. 


ILE access 


UNLOCK ( 
unlock template : space pointer 
) 


Description: The instruction releases the object locks that are specified in the unlock template. The 
template specified by operand 1 identifies the system objects and the lock states (on those objects) 
that are to be released. The unlock template must be aligned on a 16-byte boundary. The format is as 
follows: 


e Number of unlock requests in template Bin(4) 

e Offset to lock state selection bytes Bin(2) 

e Reserved (binary 0) Char(8)* 

e Unlock option - . Char(1) 
— Reserved (binary 0) Bits 0-3* 
— Unlock type Bits 4-5 


00 = Unlock specific locks now allocated to process 
01 Cancel specific asynchronously waiting lock request or allocated locks 
10 = Cancel all asynchronously waiting lock requests 


11 = Invalid 
— Reserved (binary 0) Bit 6-7 
e Reserved (binary 0) Char(1) 
« Object to unlock (one for each unlock request) System pointer 


The Unlock aptions is located by adding the offset to lock state selection bytes above to operand 1. 


e Unlock options (repeated for unlock request) Char(1) 
— Lock state to unlock (only one state Bits 0-4 
can be selected) (1 = unlock) 
LSRD Bit 0 
- LSRO Bit 1 
- LSUP Bit 2 
- LEAR Bit 3 
- LENR Bit 4 
— Lock count option Bit 5 
0= Lock count reduced by 1 
1= All locks are unlocked. The lock count is set to 0 
— Reserved (binary 0) Bit 6” 
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Unlock Object (UNLOCK) 


— Entry active indicators Bit 7 
0= Entry not active. This entry is not used. 
1 = Entry active. These locks are unlocked. 


Note: Entries indicated by an asterisk are ignored by the instruction. 


The unlock type field specifies if locks are to be released or outstanding lock requests are to be can- 
celed. 


If all asynchronous lock waits are being canceled (unlock type specified as 10 ), then objects to unlock 
and unlock options for each object are not required. If the asynchronous lock fields are provided in the 
template, then the data is ignored. 


Specifying 01 for unlock type attempts to cancel an asynchronous lock request that is identical to the 
one defined in the template. After the instruction attempts to cancel the specified request, program 
execution continues just as if 00 had been specified for unlock type. A waiting lock request is canceled 
if the number of active requests in the template, the objects, the objects corresponding lock states, and 
the order of the active entries in the template all match. 


When a lock is released, the lock count is reduced by 1 or set to 0 in the specified state. This option is 
specified by the lock count option parameter. 


If 01 is specified for unlock type is specified and the unlock count option for an object lock is 0 (lock 
count reduced by 1), then a successful cancel satisfies this request, and no additional locks on the 
object are unlocked. If the Jock count option for an object lock is set to 1 (set jock count to QO), the 
results of the cancel are disregarded, and all held locks on the object are unlocked. 


Specific locks can be unlocked only if they are allocated to the process issuing the unlock instruction. 
Implicit locks may not be unlocked with this instruction. No locks are unlocked if an entry in the tem- 
plate is invalid. 


Object locks to unlock are processed sequentially and individually. If one specific object lock cannot 
be unlocked because the process does not hold the indicated lock on the object, then exception data is 
saved, but processing of the instruction continues. 


After all requested object locks have been processed, the invalid unlock request (hex 1A03) exception 
is signaled if any object lock was not unlocked. 


If 01 is specified for unlock type is selected and the cancel attempt is unsuccessful, an invalid unlock 
request (hex 1A03) exception is signaled when any object lock in the template is not unlocked. 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialize 


— Contexts referenced for address resolution 


Exceptions 


Operands 
Exception 1 Other 
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Exception 


06 


08 


0A 


10 


1A 


20 


22 


24 


2E 


36 


38 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 
01 invalid lock state 


03 invalid unlock request 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Unlock Object (UNLOCK) 


Operands 
1 Other 
X 
X 
X 
X 
X 
X 
X X 
X 
X X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
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Cc 


Unlock Space Location (UNLOCKSL) 


Op Code (Hex) Operand 1 Operand 2 
O3F2 Space location or Lock request 
Unlock template 


Operand 1: Space pointer data object. 


Operand 2: Char(1) scalar or null. 


ILE access 
UNLOCKSL ({ 
var space location : space pointer; 
var lock request : aggregate OR 


null operand 


Unlock Space Location (UNLOCKSL) 


Description: When operand 2 is not null, the lock type specified by operand 2 is removed from the 
space location (operand 1). When the operand 2 is null, the lock type is removed for the space 


locations specified in the unlock template (operand 1). 


Any space location(s) specified by operand 1, or within the template specified by operand 1, need not 
exist when this instruction is issued although the space pointer must be a valid pointer as used to lock 


the space location. 


A space pointer machine object cannot be specified for operand 1. 


The following is the format of operand 2 when not null: 
e Lock request 


— Lock state selection 
(1 = lock requested, 0 = lock not requested) 


- Only one state may be requested. 
- LSRD lock 
- LSRO lock 
- LSUP lock 
- LEAR lock 
- LENR lock 
— Reserved (binary Q) 


Char(1) 
Bits 0-4 


Bit 0 
Bit 4 
Bit 2 
Bit 3 
Bit 4 
Bits 5-7 


If a space location lock cannot be unlocked because the process does not hold the indicated lock, then 


the invalid space location unlock (hex 1A05) exception is signaled. 


~ 


When operand 2 is null, the lock request template identified by operand 1 must be aligned on a 16-byte 


boundary. The format of operand 1 is as follows: 


e Number of space location unlock requests 
in template 


¢ Offset to lock state selection values 


e Reserved (binary 0) 
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Bin(4) 


Bin{2) 
Char(26)* 
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ee nl i 


Unlock Space Location (UNLOCKSL) 


e Space location(s) to be unlocked Space pointer 


This should be repeated as specified by number of space location unlock requests in template 
above. 


The unlock options is located by adding the offset to lock state selection values above to operand 1. 


e Unlock options Char(1) 
(repeated for each unlock request) 
— Lock state to unlock Bits 0-4 


(1 = unlock requested, 0 = unlock not requested) 


- Only one state may be requested. 


- LSRD lock Bit O 
- LSRO lock Bit 1 
- LSUP lock Bit 2 
- LEAR lock Bit 3 
- LENR lock Bit 4 
— Lock count option Bit 5 
0= Lock count reduced by 1 
{= All locks are unlocked. (The lock count is set to 0). 
— Reserved (binary 0) Bit 6 
— Entry active indicator Bit 7 
0 = Entry not active. This entry is not used. £ 
1 = Entry active. Lock is to be unlocked. wd 


Note: Entries indicated with an asterisk are ignored by the instruction. 


This instruction can request the deallocation of one or more lock states on one or more space 
locations. The locks are deallocated sequentially until all specified locks are deallocated. When a lock 
is deallocated, the lock count is either reduced by 1 or set to 0 for the specified state. This option is 


specified by the lock count option. 


Specific locks can be unlocked only if they are heid by the process issuing the unlock instruction. If a 
space location lock cannot be unlocked because the process does not hold the indicated lock, then 
exception data is saved but processing of the instruction continues. After all requested space location 
locks have been processed, the invalid unlock request (hex 1A03) exception is signaled if any space 
location lock was not unlocked. 


No locks are unlocked if a template value is invalid. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x KK OK 


08 Argument/parameter 
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Exception 


10 


1A 


1c 


20 


22 


24 


2E 


32 


36 


38 


01 parameter reference violation 


Damage encountered 
04 system object 


44 partial system object damage 


Lock state 
03 invalid unlock request 


05 invalid space location unlock 


Machine-dependent exception 
03 machine storage limit exceeded 


06 machine lock limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 
02 object destroyed 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Unlock Space Location (UNLOCKSL) 


Operands 
1 2 Other 
X 
X X 
X 
X 
X 
X 
X 
X 
X 
X X 
X 
X 
X 
X 
X X 
X 
X 
X 
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Exception Management Instructions 


Chapter 14. Exception Management Instructions J 


This chapter describes all instructions used for exception management. These instructions are in 
alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 


Materialize Exception Description (MATEXCPD) ............0. 0. 0000. eee ee ee 14-3 
Modify Exception Description (MODEXCPD) ............0.0.0 00.0000 0002 2 ee eee 14-6 
Retrieve Exception Data (RETEXCPD) ........... 0.000000 00. 2 ee ee 14-9 
Return From Exception (RTNEXCP) .... 2... 0.0.0.0. ee 14-12 
Sense Exception Description (SNSEXCPD) ...........0. 000.000 eee eee 14-15 
signal Exception (SIGEXCP): | s.9. 8! ye. ete hh ete sce wee Bs Bw A ee le eel a SE 14-19 
Test Exception (TESTEXCP) ........0.0. 0.00000 ce ee ee 14-24 
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Materialize Exception Description (MATEXCPD) 


Materialize Exception Description (MATEXCPD) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 J 
03D7 Attribute receiver Exception Materialization 
description option 


Operand 1: Space pointer. 
Operand 2: Exception description. 
Operand 3: Character(1) scalar. 


Description: The instruction materializes the attributes (operand 3) of an exception description 
(operand 2) into the receiver specified by operand 1. 


The template identified by operand 1 must be a 16-byte aligned area in the space if the materialization 
option is hex 00. 


Operand 2 identifies the exception description to be materialized. 


The value of operand 3 specifies the materialization option. If the materialization option is hex 00, the 
format of the exception description materialization is as follows: 


e Template size Char(8) 
— Number of bytes provided for materialization ‘Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Control flags Char(2) 9 
— Exception handling action Bits 0-2 


000 = Do not handle. (Ignore occurrence of exception and continue processing.) 

001 Do not handle. (Disable this exception description and continue to search this invoca- 
tion for another exception description to handle the exception.) 

010 = Do not handle. (Continue to search for an exception description by resignaling the 
exception to the preceding invocation.) 


100 = Defer handling. (Save exception data for later exception handling.) 
101 = Pass control to the specified exception handler. 
— No data Bit 3 
0 = Exception data is returned 
1 = Exception data is not returned 
— Reserved (binary 0) . Bit 4 
— User data indicator Bit 5 


O = User data not present 
1 = User data present 


— Reserved (binary 0) Bits 6-7 
— Exception handler type Bits 8-9 
0O = External entry point 


01 = Internal entry point 
10 = Branch point 
— Reserved (binary 0) Bits 10-15 
e Instruction number to be given control UBin(2) 


Chapter 14. Exception Management Instructions 14-3 


Materialize Exception Description (MATEXCPD) 


(if exception handler type is internal entry point or branch point: otherwise, 0) 


¢ Length of compare value (maximum of 32 bytes) Bin({2) 

¢ Compare value (size established by value of Char(32) 
length of compare value field) 

e Number of exception !Ds Bin(2) 


e System pointer to the exception handling 


system pointer 


program (if exception handler type is external entry point) 


e Pointer to user data (not present if value of Space pointer 
user data indicator is Q) 


e Exception ID (one for each exception ID Char(2) 
dictated by the number of exception IDs field) 


If the materialization option is hex 01, the format of the materialization is as follows: 


e Template size Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

¢ Control flags Char(2) 
— Exception handling action Bits 0-2 


000 = Do not handle. (Ignore occurrence of exception and continue processing.) 

001 = Do not handle. (Disable this exception description and continue to search this invoca- 
tion for another exception description to handle the exception.) 

010 = Do not handle. (Continue to search for an exception description by resignaling the 
exception to the preceding invocation.) 

100 = Defer handling. (Save exception data for later exception handling.) 

101 = Pass control to the specified exception handler. 


No data Bit 3 


0 
1 


Reserved (binary 0) Bit 4-15 


Exception data is returned 
Exception data is not returned 


lf the materialization option is hex 02, the format of the materialization is as follows: 


e Template size Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Compare value length (maximum of 32 bytes) Bin(2) 


« Compare value 


Char(32) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the maferialization 
length (hex 3803) exception) are signaled in the event that the receiver operand contains insufficient 


area for the materialization. 


Chapter 14. Exception Management Instructions 14-4 


Materialize Exception Description (MATEXCPD) 


Exceptions: 


Other 


e) 


Exception 1 2 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK OK 
~~ KK XK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X 


10 Damage encountered 
04 system object damage state X X X X 
44 partial system object damage X X X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check . xX 


22 Object access 
01 object not found X X 
02 object destroyed 
03 object suspended X X 


x 
~< 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X X 
02 pointer type invalid Xx X 


2E Resource contro! limit 


01 user profile storage limit exceeded X 


32 Scalar specification 


03 scalar value invalid X 


36 Space management 


01 space extension/truncation X 


38 Template specification 


03 materialization length exception X 
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Modify Exception Description (MODEXCPD) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
O3EF Exception Modifying attri- Modification 
description butes option 


Operand ?: Exception description. 
Operand 2: Space pointer or character(2) constant. 
Operand 3: Character(1) scalar. 


Description: The exception description attributes specified by operand 3 are modified with the values 
of operand 2. 


Operand 1 references the exception description. 


Operand 2 specifies the new attribute values. Operand 2 may be either a character constant or a 
space pointer to the modification template. When operand 3 is a constant, operand 2 is a character 
constant; when operand 3 is not a constant, operand 2 is a space pointer. 


The value of operand 3 specifies the modification option. If the modification option is hex 01 and 
operand 2 specifies a space pointer, the format of the modifying attributes pointed to by operand 2 is 
as follows: 


e Template size “Char(8) 
— Number of bytes provided for materialization Bin(4) 
(must be at least 10) 
— Number of bytes available for materialization Bin(4)* 
¢ Control flags Char(2) 
— Exception handling action Bits 0-2 


000 = Do not handle. (Ignore occurrence of exception and continue processing.) 

001 = Do not handle. (Disable this exception description and continue to search this invoca- 
tion for another exception description to handle the exception.) 

010 = Do not handle. (Continue to search for an exception description by resignaling the 
exception to the preceding invocation.) 

100 = Defer handling. (Save exception data for later exception handling.) 

101 = Pass control to the specified exception handler. 


— No data | Bit 3 


O = Exception data is returned 
1 Exception data is not returned 


— Reserved (binary 0) Bits 4-15 


If the exception description was in the deferred state prior to the modification, the deferred signal, if 
present, is lost. 


When the no data field is set to exception data is not returned, no data is returned for the Retrieve 
Exception Data or Test Exception instructions, and the number of bytes available for materialization 
field is set to 0. This option can also be selected in the object definition table entry of the exception 
description. 
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If the modification option of operand 3 is a constant value of hex 01, then operand 2 may specify a 
character constant. The operand 2 constant has the same format as the control flags entry previously 
described. ; ao 


If the modification option is hex 02, then operand 2 must specify a space pointer. The format of the 
modification is as follows: 


« Template size Char(8) 
— Number of bytes provided Bin(4) 
(must be at least 10 plus the length of the compare value in the exception description) 
— Number of bytes available for materialization Bin(4)* 
e Compare value length Bin(2)* 


(maximum of 32 bytes) 
« Compare value Char(32) 
Note: Entries shown here with an asterisk (*) are ignored by the instruction. 
The number of bytes in the compare vaiue is dictated by the compare value length specified in the 
exception description as originally specified in the object definition table. 


An external exception handling program can be modified by resolving addressability to a new program 
into the system pointer designated for the exception description. 


The presence of user data is not a modifiable attribute of exception descriptions. If the exception 
description has user data, it can be modified by changing the value of the data object specified in the 
exception description. 


Exceptions “wa 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X 
03 range X X 
06 optimized addressability invalid X X 
08 Argument/parameter 
01 parameter reference violation X X 
10 Damage encountered 
04 system object damage state , 4 X X Xx 
44 partial system object damage X X X X 
1C Machine-dependent exception 
03 machine storage limit exceeded X 
20 Machine support 
02 machine check X 
03 function check X 
22 Object access 
01 object not found X X 
02 object destroyed X X 
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Exception 


24 


2E 


32 


36 


38 


03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource contro! limit 


01 user profile storage limit exceeded 


Scalar specification 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 


02 template size invalid 


Modify Exception Description (MODEXCPD) 


Operands 
1 2 3 Other 
X X 
X 
X X 
X X 
X 
X 
X 
X 
X 
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Retrieve Exception Data (RETEXCPD) 


Operand 2 J 


Retrieve options 


Op Code (Hex) Operand 1 
O3E2 Receiver 


Operand f: Space pointer. 
Operand 2: Character(‘1) scalar. 


Description: The data related to a particular occurrence of an exception is returned and placed in the 
specified space. 


Operand 1 is a space pointer that identifies the receiver template. The template identified by operand 
1 must be 16-byte aligned in the space. 


The value of operand 2 specifies the type of exception handler for which the exception data is to be 
retrieved. The exception handler may be a branch point exception handler, an internal entry point 
exception handler, or an external entry point exception handler. 


An exception state of process invalid (hex 1602) exception is signaled to the invocation issuing the 
Retrieve Exception Data instruction if the retrieve option is not consistent with the process’s exception 
handling state. For example, the exception is signaled if the retrieve option specifies retrieve for 
internal entry point exception handler and the process exception state indicates that an internal excep- 
tion handler has not been invoked. 


After an invocation has been destroyed, exception data associated with a signaled exception 
description within that invocation is lost. 


The format of operand 1 for the materialization is as follows: 


Template size 

— Number of bytes provided for retrieval 
— Number of bytes available for retrieval 
Exception identification 

Compare value length (maximum of 32 bytes) 
Compare value 

Message reference key 

Exception specific data 

Source invocation 

Target invocation 

source invocation address 

Target invocation address 


Machine-dependent data 


Char(8) 

Bin(4) 

Bin(4) 

Char(2) 

Bin(2) 

Char(32) 

Char(4) 

Char(*) 

Invocation pointer or Null 
Invocation pointer 
UBin(2) 

UBin(2) 

Char(10) 


The first 4 bytes of the materialization identify the total number of bytes provided for retrieval of the 
exception data. This value is supplied as input to the instruction and is not modified by the instruction. 


A value of less than 8 causes the materialization length exception (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 


2 


ized. The instruction materializes as many bytes as can be contained in the area specified as the 
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receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested. then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
the materialization. 


The message reference key field returns the architected value that uniquely identifies the message in 
the process queue space. 


The source invocation and source invocation address identify the invocation that caused the exception 
to be signaled. For machine exceptions, this invocation pointer identifies the invocation executing 
when the exception occurred. For user-signaled exceptions, this invocation pointer locates the invoca- 
tion that executed the Signal Exception instruction or the Send Process Message instruction. The 
pointer will be null if the source invocation no longer exists at the time that this instruction is executed. 
The source instruction address field locates the instruction that caused the exception to be signaled. 
This field in a bound program invocation will be set to 0. 


The target invocation and target invocation address identify the invocation that is the target of the 
exception. This invocation is the last invocation that was given the chance to handle the exception. 
For machine exceptions, the first target invocation is the invocation incurring the exception. For user- 
signaled exceptions, the Signal Exception instruction may initially locate the current or any previous 
invocation. For Send Process Message, the source and target invocations are specified as input 
parameters. If the target invocation handles the exception by resignaling the exception, the imme- 
diately previous invocation is considered to be the target invocation. This may occur repetitively until 
no more prior invocations exist in the process and the signaled program invocation entry is assigned a 
value of binary 0. If an invocation handles the exception in any manner other than resignaling or does 
not handle the exception, that invocation is considered to be the target. 


The target instruction address field specifies the number of the instruction that is currently being exe- 
cuted in the target invocation. 


The machine extends the area beyond the exception specific data area with binary 0’s so that the 
pointers to program invocations are aligned on a 16 byte boundary. 
The operand 2 values are defined as follows: 

¢ Retrieve options Char(‘) 


- Hex 00 = Retrieve for a branch point exception handler 
- Hex 01 Retrieve for an internal entry point exception handler 
- Hex 02 = Retrieve for an external entry point exception handler 


If the exception data retention option is set to 1 (do not save), the number of bytes available for 
retrieval is set to 0. 


Exception data is always available to the process default exception handler. 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation X X 
02 boundary alignment X X 
03 range X X 
X X 


06 optimized addressability invalid 
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Exception 


08 


1C 


20 


22 


24 


2E 


32 


36 


38 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Exception management 


02 exception state of process invalid 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 


08 object compressed 


Pointer specification 


01 pointer does not exist 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Retrieve Exception Data (RETEXCPD) 


Operands 
1 2 Other 
X X 
X X X 
X X X 
X 
X 
X 
X 
X X 
X X 
X Xx 
X 
X X 
X 
xX 
X 
X 
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Return From Exception (RTNEXCP) 


Op Code (Hex) Operand 1 
O3E1 Return target 


Operand ?: Space pointer. 


Description: An internal exception handler subinvocation or an external exception handler invocation 
is terminated, and control is passed to the specified instruction in the specified invocation. All inter- 
vening invocations are marked as cancelled, down to, but not including, the invocation that is being 
returned to. When each of these invocations are returned to, their return handlers and invaocation exit 
(l-exit) routines/cancel handlers will be found and run. 


Note: This instruction is not allowed from a bound program invocation. 
The template identified by operand 1 must be 16-byte aligned in the space. It specifies the target invo- 


cation and target instruction in the invocation where control is to be passed. The format of operand 1 
is as follows: 


e Invocation address/offset Space/Invocation pointer 
e Reserved (binary 0) Char(1) 
e Action Char(2) 
— Reserved (binary 0) Bits 0-4 
— Use offset option " Bit 5 
O = Use invocation address as a pointer value 


4 = Use invocation address as an offset value 
— Unstack option Bit 6 


O = The action performed is determined by the setting of the following action code (bit 7). 

1 = If the exception handler is an internal exception handler, resume execution with the 
instruction that follows the RTNEXCP instruction and terminate the internal exception 
handler subinvocation. 


— Action code Bit 7 
O = Re-execute the instruction that caused the exception or the instruction that invoked the 
invocation. 


1 = Resume execution with the instruction that follows the instruction that caused the excep- 
tion or resume execution with the instruction that follows the instruction that invoked the 
invocation. 


— Reserved (binary 0) Char(1) 


The invocation address/offset field is a space/invocation pointer that identifies the invocation to which 
contro! will be passed. 


The target invocation address field can also be an offset value from the current requesting invocation 
to the invocation to be searched. This is done by setting the use offset option field that follows the 
invocation address field to 1. If the invocation offset value locates the invocation stack base entry, the 
invocation offset outside range of current stack (hex 2C1A) exception is signaled. If the invocation 
offset value is a positive number (which represents newer invocations on the stack) a template value 
invalid (hex 3801) exception is signaled. The current instruction in an invocation is the one that caused 
another invocation to be created. 


The unstack option is only valid when issued in an internal exception handler subinvocation and is 
ignored for an external exception handler invocation. This option will cause the internal exception 
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handler subinvocation to be terminated and control will resume at the instruction immediately following 
the RTNEXCP instruction. In effect, this option will cause the current subinvocation to be unstacked. 


If the action code is 0, then the current instruction of the addressed invocation is reexecuted, if it is J 
allowed. If the action code is 1, execution resumes with the instruction following the current instruction 

of the addressed invocation, if it is allowed. If it is not, a retry/resume invalid (hex 1604) exception will 

be signaled. 


The Return From Exception instruction may be issued only from the initial invocation of an external 
exception handling sequence or from an invocation that has an active internal exception handler. 


If the instruction is issued from an invocation that is not an external exception handler and has no 
internal exception handler subinvocations, the return instruction invalid (hex 2C01) exception is sig- 
naled. 


The following table shows the actions performed by the Return From Exception instruction: 


Invocation Addressing Addressing 

Issuing Own Higher 

instruction Invocation/Option Invocation/Option 
Not handling exception Error (see note 1) Error (sse note 1) 
Handling internal exception(s) Allowed (see note 2) Allowed (see note 3) 
Handling external exception(s) Error (see note 1) Allowed (see note 3) 
Handling external exception(s) Allowed (see note 2) Allowed (see note 3) 


and internal exception(s) 


Notes: ; 
1. A return instruction invalid (hex 2C01) exception is signaled. \f there are no more internal excep- J 
tion handler subinvocations active and this invocation is not an external exception handler, the 
instruction may not be issued. 


2. The current internal exception handler subinvocation is terminated. 


3. All invocations after the addressed invocation are terminated and execution proceeds within the 
addressed invocation. Any invocation exit programs set for the terminated invocations will be 
given control before execution proceeds within the addressed invocation. 


Whenever an invocation is terminated, the invocation count in the corresponding activation entry (if 
any) is decremented by 1. 


An action code of 1 specifies completion of an instruction rather than execution of the following instruc- 
tion if the current instruction in the addressed invocation signaled a size exception or a floating-point 
inexact result exception. 


Note: The previous condition does not apply if any of the above exceptions were explicitly signaled by 
a Signal Exception instruction. 


A Return From Exception instruction cannot be used or recognized in conjunction with a branch point 
internal exception handler. 


lf a failure to invoke an invocation exit handler occurs, a failure to invoke program event is signaled. 


Exceptions 

Operands f 
Exception 1 Other we 
06 Addressing 
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Exception 


08 


16 


1c 


20 


22 


24 


2C 


2E 


36 


38 


01 space addressing violation 
02 boundary alignment 
03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Exception management 
03 invalid invocation 


04 retry/resume invalid 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


01 return instruction invalid 


12 activation group access protection violation 


1A invocation offset outside range of current stack 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Return From Exception (RTNEXCP) 


Operands 
1 Other 
X 
X 
X 
X 
X 
X X 
X X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
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Sense Exception Description (SNSEXCPD) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 J 
O3E3 Attribute receiver Invocation tem- Exception tem- 
plate plate 


Operand 1: Space pointer. 
Operand 2: Space pointer. 


Operand 3: Space pointer. 


Note: A change has been made in the way in which exceptions are handled for bound programs. This 
instruction is intended for use with Original Program Model (OPM) programs, but can be used against 
New Program Model (NPM) bound programs. The data that is returned when an NPM program is 
accessed will always say that there is an external handler for the sensed exception, that there is no 
exception data being returned and a starting exception description number of 0. 


Description: The Sense Exception Description instruction searches the invocation specified by 
operand 2 for an exception description that matches the exception identifier and compare value speci- 
fied by operand 3 and returns the user data and exception handling action specified in the exception 
description. The exception descriptions of the invocation are searched in ascending Object Definition 
Table (ODT) number sequence. 


The template identified by operand 1 must be 16-byte aligned. 


The format of the attribute receiver is as follows: 


e Template size Char(8) J 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Control flags Char(2) 
— Exception handling action Bits 0-2 


000 = Do not handle- Ignore occurrence of exception and continue processing 

010 = Do not handle- Continue search for an exception description by resignaling the excep- 
tion to the immediately preceding invocation 

100 = Defer handling- Save exception data for later exception handling 

101 = Pass control to the specified exception handler 


— No data Bit 3 


0 Exception data is returned 
1 = Exception data is not returned 


— Reserved (binary 0) Bit 4 


— User data indicator Bit 5 


l 


O = User data not present 
1 = User data present 


— Reserved (binary 0) Bits 6-7 
— Exception handler type Bits 8-9 
00 = External entry point . ) 


01 = Internal entry point 
10 = Branch point 
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— Reserved (binary 0) Bits 10-15 
« Relative exception description number Bin(2) 
« Reserved (binary 0) Char(4) 
e Pointer to user data (binary 0 if value of Space pointer 


user Gata indicator is Q) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exception is signaled in the event the 
receiver contains insufficient area for the materialization, other than the materialization length (hex 
3803) exception described previously. 


The relative exception description number field identifies the relative number of the exception 
description that matched the search criteria. The order of definition of the exception descriptions in 
the ODT determines the value of the index. A value of 1 indicates that the first exception description 
defined in the ODT matched the search criteria. 


The format of the invocation template is as follows: 


e Invocation address/offset ‘Space/Invocation pointer 
e Search flags Char(2) 
— Use offset option Bit O 


O = Use invocation address as a pointer value 
1 = Use invocation address as an offset value 


— Reserved (binary 0) Bits 1-15 


¢ First exception description to search Bin(2) 


The template identified by operand 2 must be 16-byte aligned. The invocation address/offset field is a 
space/invocation pointer that identifies the invocation to be searched. The invocation is searched for a 
matching exception description. If the invocation address locates either an invalid invocation or the 
invocation stack base entry, the invalid invocation address (hex 1603) exception is signaled. 


The invocation address/offset field can also be an offset value from the current requesting invocation to 
the invocation to be searched. This is setting the use offset option bit field that follows the invocation 
address field to 1. If the invocation offset value locates the invocation stack base entry, the invocation 
offset outside range of current stack (hex 2C1A) exception is signaled. If the invocation offset value is 
positive or zero, a template value invalid (hex 3803) exception is signaled. 


The first exception description to search field specifies the relative number of the exception description 
to be used to start the search. The number must be a nonzero positive binary number determined by 
the order of definition of exception descriptions in the ODT. A value of 1 indicates that the first excep- 
tion description in the invocation is to be used to begin the search. If the value is greater than the 
number of exception descriptions for the invocation, the operand 1 template is materialized with the 
number of bytes available for materialization set to 0. 


The operand 3 exception template specifies the exception-related data to be used as a search argu- 
ment. The format of the template is as follows: 


e Template size Char(8) 
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— Number of bytes provided for materialization Bin(4) 
(must be at least 44) 
— Number of bytes available for materialization Bin(4)* J 
¢ Exception identifier Char(2) 
* Compare value length (maximum of 32) Bin(2) 
e Compare value Char(32) 


Note: Entries noted with an asterisk (*) are ignored by the instruction. 


The exception identifier in the exception description can be specified in one of the following ways: 
Hex 0000 = Any exception ID will result in a match 

Hex nn0OO = Any exception ID in class nn will result in a match 

Hex nnmm = Only exception ID nnmm will result in a match 


If a match on exception ID is detected, the corresponding compare values are matched. If the compare 
value length in the exception description is less than the compare value in the search template, the 
length of the compare value in the exception description is used for the match. If the compare value 
length in the exception description is greater than the compare value in the search template, an auto- 
matic mismatch results. 


If a match on exception ID and compare value is detected, the exception handling action of the excep- 
tion description determines which of the following actions is taken: 
IGNORE The operand 1 template is materialized. 


DISABLE The exception description is bypassed and the search for an exception description continues ‘ 
with the next exception description defined for the invocation. oe 


RESIGNAL The operand 1 template is materialized. 
DEFER The operand 1 template is materialized. 
HANDLE The operand 1 template is materialized. 


If no exception description of the invocation matches the exception ID and compare value of operand 3, 
the number of bytes available for materialization on the operand 1 template is set to 0. 


Exceptions 

Operands 
Exception 1 2 3 Other 
06 Addressing 


01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


x KK XK 
x KX K OK 
x KK XK 


08 Argument/parameter 
01 parameter reference violation xX X X 
10 Damage encountered 
04 system object damage X 
44 partial system object damage X 
16 Exception management 
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Exception 


e 


20 


22 


24 


2C 


2E 


32 


36 


38 


03 invalid invocation address 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


1A invocation offset outside range of current stack 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 
02 template size invalid 


03 materialization length exception 


Sense Exception Description (SNSEXCPD) 


Operands 
1 2 3 Other 
X 
X 
X 
X 
X X X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X X X 
X 
X X 
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Signal Exception (SIGEXCP) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3-4 2 
SIGEXCP Attribute template Exception data 

10CA 

SIGEXCPB Branch options Attribute template Exception data Branch targets 

1CCA 

SIGEXCPI Indicator options Attribute template Exception data Indicator targets 

18CA 


Operand 1: Space pointer. 
Operand 2: Space pointer. 


Operand 3-4: 


e Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The Signal Exception instruction signais a new exception or resignals an existing excep- 
tion to the process. Optionally, the instruction branches to one of the specified targets based on the 
results of the signal and the selected branch options in the extender field, or it sets indicators based 
on the results of the signal. The signal is presented starting at the invocation identified in the signal 


template. ¥ 
23 


The SIGEXCP instruction is a subset of the Send Process Message (SNDPRMSG) instruction. Addi- 
tional parameters used in the SNDPRMSG instruction will be defaulted when the SIGEXCP instruction 
is used. See the SNDPRMSG instruction for more information about the complete set of parameters 
available when signalling an exception. 


The template identified by operand 1 specifies the signal option and starting point. It must be 16-byte 
aligned in the space with the following format. 


e Target invocation address Space/Invocation pointer 
« Signal option Char(1) 
— Signal/resignal option Bit O 
0 = Signal new exception. 


1 


— Invoke PDEH (process default Bit 1 
exception handler) option 


Resignal currently handled exception (valid only for an external exception handler). 


0 = Invoke PDEH if no exception description found for invocation. 
1 = Do not invoke PDEH if no exception description found for invocation (ignore if base invo- 
cation entry specified). 


— Exception description search control Bit 2 


0 = Exception description search control not present 
1 = Exception description present 


— Reserved (binary 0) Bits 3-7 
e Reserved (binary 0) Char(1) 
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° First exception description to search Bin(2) 


The target invocation address pointer uniquely identifies the invocation to which the exception is to be 
signalled. Signalling directly to the PDEH can not be accomlished via this instruction. Support for this 
function is being provided in the SNDPRMSG instruction. If the target invocation address pointer 
locates neither a valid invocation entry nor the base invocation entry, the invalid invocation (hex 1603) 
exception is signaled. 


The invocation which issued this instruction will be checked to ensure it has the proper authority to 
send an exception message to the target invocation. If the authority check fails, activation group 
access violation (hex 2C12) will be signaled. If the program associated with the invocation has defined 
an exception description to handle the exception, the specified action is taken; otherwise, the PDEH is 
invoked unless the invoke PDEH option bit is 1 (the exception is considered ignored). If the base invo- 
cation entry is addressed instead of an existing invocation, the PDEH will be invoked. 


A change has been made to the way in which exception handlers are determined for bound programs. 
The following description relates only to the invocation of exception handlers related to OPM pro- 
grams. In both instances the actions of signalling and handling have been broken apart. 


Note: 


Exception descriptions of an invocation are searched in ascending ODT number sequence. [lf 
the exception description search control control specified that an exception description is not 
present, the search begins with the first exception description defined in the ODT. Otherwise, 
the first exception description to search value identifies the relative number of the exception 
description to be used to start the search. The value must be a nonzero positive binary number 
determined by the order of definition of exception descriptions in the ODT. This value is also 
returned by the Sense Exception Description instruction. A value of 1 indicates that the first 
exception description in the invocation is to be used to begin the search. If the value is greater 
than the number of exception descriptions for the invocation, the template value invalid (hex 
3801) exception is signaled. 


If an exception ID in an exception description corresponds to the signaled exception, the corre- 
sponding compare vaiues are verified. If the compare value length in the exception description 
is less than the compare value Jength in the signal template, the length of the compare value in 
the exception description is used for the match. If the compare vaiue length in the exception 
description is greater than the compare value length in the signal template, an automatic mis- 
match results. Machine-signaled exceptions have a 4-byte compare value of binary 0’s. 


An exception description may monitor for an exception with a generic ID as follows: 

Hex 0000 = Any signaled exception ID results in a match. 

Hex nnOQO = Any signaled exception ID in class nn results in a match. 

Hex nnmm = The signaled exception ID must be exactly nnmm in order for a match to occur. 
An exception description may be in one of five states, each of which determines an action to be 
taken when the match criteria on the exception ID and compare value are met. 


IGNORE No exception handling occurs. The Signal Exception instruction is assigned a 
resultant condition of ignored. If a corresponding branch or indicator setting is 
present, that action takes place. 


DISABLE The exception description is bypassed, and the search for a monitor continues with 
the next exception description defined for the invocation. 
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RESIGNAL The search for a monitoring exception description is to be reinitiated at the pre- 
ceding invocation. A resignal from the initial invocation in the process results in the 
invocation of the process default exception handler. A resignal from an invocation 
exit program results in an unhandled exception that causes process termination. 


DEFER The exception description is signaled, and the Signal Exception instruction is 
assigned the resultant condition of deferred. If a corresponding branch or indicator 
setting is present, that action takes place. To take future action on a deferred excep- 
tion, the exception description must be synchronously tested with the Test Exception 
instruction in the signaled invocation. 


HANDLE Control is passed to the indicated exception handler, which may be a branch point, an 
internal subinvocation, or an external invocation. 


lf the exception description is in the ignore or defer state and if the Signal Exception instruction 
does not specify a branch or indicator condition or if it specifies branch or indicator conditions 
that are not met, then the instruction following the Signal Exception instruction is executed. 


When control is given to an internal or branch point exception handler, all invocations up to, but 
not including, the exception handling invocation are terminated. Any invocation exit programs 
set for the terminated invocations will be given control before execution proceeds in the sig- 
naled exception handler. 


When this instruction is invoked with the Resignal option, all invocations up to, but not including, the 
interrupted invocation are cancelled and the message is signalled to the next oldest invocation in the 
stack. This implies that the Return from Exception (RTNEXCP) instruction can no longer return to the 
invocation that issued the resignal request. Any cancel handlers set for the cancelled invocations will 
be given control before execution proceeds in the signaled exception handler. 


‘ 
lf a failure to invoke an external exception handler or an invocation exit occurs, a failure to invoke ») 
program event is signaled. For each destroyed invocation, the invocation count in the corresponding 
activation entry (if any) is decremented by 1. 


The template identified by operand 2 must be 16-byte aligned in the space. It specifies the exception- 
related data to be passed with the exception signal. The format of the exception data is the same as 
that returned by the Retrieve Exception Data instruction. The format is as follows: 


e Template size Char(8) 
— Number of bytes of data to be signaled Bin(4) 
(must be at least 48 bytes) 
— Number of bytes available for materialization Bin(4)* 
e Exception identification Char(2) 
« Compare value length (maximum of 32 bytes) Bin (2) 
e Compare value Char(32) 
¢ Reserved Char(4)" 
e Exception specific data Char(*) 


Note: Entries shown here with an asterisk (*) are ignored by the instruction. 


Operand 2 is ignored if signa//resignal option is resignal because the exception-related data is the 
same as for the exception currently being processed; however, it must be specified when signaling a 
new exception. 


The maximum size for exception specific data that is to accompany an exception signaled by the Signal 2 
Exception instruction is 65 503 bytes, including the standard exception data. 
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The following required parameters only available on the SNDPRMSG instruction will be given the fol- 
lowing default values: 


Initial monitor priority - 64 


Resultant Conditions 


« Exception ignored 


e Exception deferred. 


Message status - Log message + Retain + Action pending 


Interrupt class mask - Message generated by Signal Exception instruction 


Source invocation - invocation issuing SIGEXCP instruction 


Authorization Required: The invocation which originated the exception must have proper acti- 
vation group access to the target invocation. The following algorithm is used to determine this access. 


1. The invocation which invoked the SIGEXCP instruction must have access to the invocation identi- 


fied as the Originating Invocation. 


2. The Originating Invocation must have access to the invocation identified as the Source Invocation 


or to the invocation directly called by the Source invocation. 


3. The Originating Invocation must have access to the invocation identified as the Target Invocation or 


to the invocation directly called by the Target Invocation. 


If any of the access checks fail then an activation group access violation (hex 2C12) exception will be 
signaled. 


Exceptions 


Exception 


06 


08 


16 


1C 


20 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Exception management 
02 exception state of process invalid 


03 invalid invocation 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 


02 machine check 


Operands 


1 2 Other 


X X 

X X 

X X 

X X 

X X 

X X X 

X X X 
X 

X 
X 
X 
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Exception 


22 


24 


2C 


2E 


36 


38 


03 function check 


Object access 

01 abject not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


12 activation group access violation 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 


02 template size invalid 


Signal Exception (SIGEXCP) 


Operands 
1 2 Other 
, J 
X X 
Xx X 
X X 
X 
X X 
X X 
XK 
X 
X 
X 
X 
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Op Code (Hex) Extender Operand 1 Operand 2 Operand 3-4 
TESTEXCP Receiver Exception 

104A description 

TESTEXCPB Branch options Receiver Exception Branch options 
1C4A description 

TESTEXCPI Indicator options Receiver Exception Indicator options 
184A description 


Operand 7: Space pointer. 
Operand 2: Exception description. 


Operand 3-4. 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ Indicator Form-Numeric variable scalar or character variable scalar. 


Description: The instruction tests the signaled status of the exception description specified in operand 
2, and optionally alters the control flow or sets the specified indicators based on the test. Exception 
data is returned at the location identified by operand 1. The branch or indicator setting occurs based 
on the conditions specified in the extender field depending on whether or not the specified exception 
description is signaled. 


Operand 2 is an exception description whose signaled status is to be tested. An exception can be 
signaled only if the referenced exception description is in the deferred state. 


Operand 1 addresses a space into which the exception data is placed if an exception identified by the 
exception description has been signaled. 


The template identified by operand 1 must be 16-byte aligned in the space and is formatted as follows: 


e Template size Char(8) 

— Number of bytes provided for materialization Bin(4) 

— Number of bytes available for materialization Bin(4) 

(0 if exception description is not signaled) 

e Exception identification Char(2) 
e Compare value length (maximum of 32 bytes) Bin(2) 
e Compare value Char(32) 
« Message reference key Char(4) 
¢ Exception-specific data Char(*) 
« Source invocation address Invocation/Null pointer 
*« Target invocation address Invocation pointer 
¢« Signaling program instruction address UBin(2) 
e Signaled program instruction address UBin(2) 
e Machine-dependent data Char(10) 
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The first 4 bytes of the materialization identify the total number of bytes provided for use by the 
instruction. This value is supplied as input to the instruction and is not modified by the instruction. A 
value of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. |f the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
the materialization. 


If the exception description is not in the signaled state, the number of bytes available for the 
materialization entry is set to binary 0’s, and no other bytes are modified. 


The message reference key field holds the architected value that uniquely identifies the exception 
message in a process queue space. 


The source invocation address field will contain a null pointer if the source invocation no longer exists 
when this instruction is executed. 


The area beyond the exception-specific data area is extended with binary 0’s so that pointers to 
program invocations are properly aligned. 


If no branch options are specified, instruction execution proceeds at the instruction following the Test 
Exception instruction. 


If the exception data retention option, from the exception description, is set to 1 (do not save), no data 
is returned by this instruction. 
Resultant Conditions 

e Exception signaled 


e Exception not signaled. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X 

02 boundary alignment X 

03 range Xx 

06 optimized addressability invalid X 
08 Argument/parameter 

01 parameter reference violation x 
10 Damage encountered 

04 system object damage state X X X 

44 partial system object damage X X X 
16 Exception management 

01 exception description status invalid X 
1C Machine-dependent exception 
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Cc 


Exception 


20 


22 


24 


2E 


36 


38 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Test Exception (TESTEXCP) 


Operands 

1 2 Other 
x 
X 
X 
X 

X 

X 
X 
X 

X 
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Chapter 15. Queue Space Management Instructions 


This chapter describes the instructions used for queue space management. These instructions are in 
alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 


Materialize Process Message (MATPRMSG) ............0 0.00 ee eee ee 15-3 


© Copyright IBM Corp. 1991, 1993 15-1 


Queue Space Management Instructions 
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Materialize Process Message (MATPRMSG) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 Operand 4 J 
039C Materialization Message template Source template Selection template 
template 


Operand 1: Space pointer 
Operand 2: Space pointer 
Operand 3: Space pointer or null 


Operand 4: Space pointer 


ILE access 
MATPRMSG ( 
receiver_template : space pointer; 
message template : Space pointer; 
source_template : space pointer; OR 


null operand; 
selection_template : space pointer 


Description: A message is materialized from a queue space according to the options specified. The 
message is located on a queue space queue specified by operand 3. The message is selected by the j 
operand 4 criteria. Operands 7? and 2 contain the materialized information from the process message. } 


The template identified by operand 7 must be 16-byte aligned. Following is the format of the 
materialization template: 


Template size specification Char(8)* 

— Number of bytes provided for materialization Bin(4) 

— Number of bytes available for materialization Bin(4) 
e Process queue space queue offset Bin(4) 
e Reserved (binary 0) Char(4) 
¢ Time sent Char(8) 
« Time modified Char(8) 
¢ Interupted invocation Invocation pointer 
¢« Target invocation Invocation pointer, or 

System pointer 

e« Original target invocation Invocation pointer 
e Source program location Suspend pointer 
¢ Target program location Suspend pointer 
¢ Originating program location Suspend pointer 
e Invocation mark UBin(4) : 
¢ Activation group mark UBin(4) 2 
e Reserved (binary 0) Char(8) 
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The first 4 bytes of the materialization template identify the total number of bytes provided for use by 
the instruction. This number is supplied as input to the instruction and is not modified by the instruc- 
tion. If the value is zero for this field, then the operand 1 template is not returned. A number less than 
128 (but not 0) causes the materialization length (hex 3803) exception. 


Queue space queue offset 


This value indicates which queue in the queue space a message resides on. A value of -' 
will be returned if the message is on the external queue, and Zero if the message is on the 
message log. If the message resides on an invocation queue this field will be zero. 


Time sent 
The value of the system time-of-day clock when the message was originally sent (Send 
Process Message instruction, Signal Exception, or message originated as a result of an 
exception). 


Time modified 
This value is initially equal to the time sent value. However, it can be modified by the Modify 


Process Message instruction. 


Interrupted invocation 
An invocation pointer that addresses the invocation which currently has this message as its 


interrupt cause. This pointer is null if the message is not an exception message. 


Target invocation 
An invocation pointer or system pointer that identifies which queue contains the message. 


lf the message resides on an invocation queue, this field contains an invocation pointer that 
addresses the invocation whose invocation message queue currently contains the message. 
lf the message does not reside on an invocation queue, then a system pointer to the Queue 
Space is returned. The queue space queue offset field indicates which queue on which the 
message resides, the message log or the external queue. 


Original target invocation 
An invocation pointer that addresses the invocation which originally was sent the message. 


This pointer is null if the original target invocation no longer exists. 


Source program location 
A suspend pointer which identifies the program, module, procedure, and statement where 


the source invocation was suspended (due to a CALL or some form of interrupt). If the 
message was originally sent as a non-interrupt message, then the source invocation is the 
one identified by the Send Process Message instruction, and the suspend point identified is 
the one that was current when that instruction was executed; otherwise the source invoca- 
tion is the invocation for which the message was most recently an interrupt cause. 


Target program location 
A suspend pointer which identifies the program, module, procedure, and statement where 


the target invocation was suspended (due to a CALL or some form of interrupt). If the 
message is no longer in an invocation message queue, then this pointer reflects the invoca- 
tion of the last (most recent) invocation message queue in which the message resided. This 
pointer is null if the message has never resided in an invocation message queue. 


Originating program location 
A suspend pointer which identifies the program, module, procedure, and statement of the 


Send Process Message instruction that sent the message. For messages sent by the 
machine, this pointer area contains a machine-dependent representation of the source 
machine component. 


Invocation mark 
lf the message has ever resided on an invocation, this field will be non-zero. It contains the 
mark of the invocation where the message was last queued. 
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Activation group mark 
If the message has ever resided on an invocation. this field will be non-zero. It contains the 


| 
| 
| 
| mark of the activation group which contains the invocation where the message was last J 
| queued. | 


| The template identified by operand 2 is used to contain the materialized message. It must be 16-byte 
| aligned with the following format. 


| © Template size 


— Number of bytes provided for materialization Bin(4) 

— Number of bytes available for materialization Bin(4) 
¢ Message type Char(1) 

— hex 00 = Informational message 0 

— hex 01 = Informational message 1 

— hex 04 = Exception message 

— hex 06 = Return/Transfer Control message 


— hex 07 = Return message 


All other values are reserved. 


¢ Reserved (binary 0) Char(‘) 
e Message severity ; Bin(2) 
e Reply/Inquiry message reference key Char(4) 
e Message status mask Char(8) ‘ 
— Log message Bit 0 wd 


O = The message is not queued to the Process Message Log. 
1 = The message is queued to the Process Message Log. 


— Inquiry Bit 1 


1 = Message will accept a reply. 


— Reply Bit 2 
O = Message does not represent a reply message. 
1 = Message represents a reply message. 
— Answered Bit 3 
0 = For messages with a status of inquiry, this indicates that a reply message has not been 
received. 
1 = For messages with a status of inquiry, this indicates that a reply message has been 
received. 
— Message being processed Bit 4 


0 = This value of the flag has no particular meaning. 
1 = For a message type of exception, this indicates that the interrupt is currently being 


handled. 
— Retain Bit 5 
0 = Message will be dequeued and its contents discarded when the following message status o 
bits are FALSE: Log, Message being processed, and Action pending. 2 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| O = Message will not accept a reply. 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


1 = Keeps the message from being dequeued after all other message status bits are FALSE. 
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— Action pending Bit 6 
0 = Indicates no actions are pending based on this message. 
1 = Indicates that the message is either an interrupt cause or is a Return, Return/Transfer 
Control message. 
— Invoke Process Default Exception Handler (PDEH) Bit 7 
0 = Do not invoke PDEH. 
1 = Invoke PDEH, only valid if message type is exception. 
— Error Bit 8 
OQ = No error has occurred in the sending of this message. 
1 = An error has occurred in the sending of this message. 
— PDEH previously invoked Bit 9 
OQ = PDEH has not previously been invoked for this message. 
1 = PDEH has previously been invoked for this message. 
— Reserved (binary 0) Bits 10-31 
— User defined status Bits 32-63 
Interrupt class mask Char(8) 
— Binary overflow or divide by zero Bit 0 
— Decimal overflow or divide by zero Bit 1 
— Decimal data error .Bit 2 
— Floating-point overflow or divide by zero Bit 3 
— Floating-point underflow or inexact result Bit 4 
— Floating-point invalid operand or conversion error Bit 5 
— Other data error (edit mask, etc) Bit 6 
— Specification (operand alignment) error Bit 7 
— Pointer not set/pointer type invalid Bit 8 
— Object not found Bit 9 
— Object destroyed Bit 10 
— Address computation underflow/overflow Bit 11 
— Space not ailocated as specified offset Bit 12 
— Domain/State protection violation Bit 13 
—- Authorization violation Bit 14 
— Reserved (binary 0) Bit 15-28 
— Other Mi generated exception (not function check) Bit 29 
— MI generated function check/machine check Bit 30 
— Message generated by Signal Exception instruction Bit 31 
— Send Process Message instruction Bit 32 
— Send Process Message instruction Bit 33 
— Send Process Message instruction Bit 34 
— Send Process Message instruction Bit 35 
— Send Process Message instruction Bit 36 


Materialize Process Message (MATPRMSG) 
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— Send Process Message instruction 
— Send Process Message instruction 


— Send Process Message instruction 


— User defined 
« Initial handler priority 
e« Current handler priority 
e Exception ID 
¢ PDEH Reason Code 
e Reserved (binary 0) 
« Compare data length 
e Message ID 
e Reserved (binary 0) 
e Max message data length 


e Message data length 


e Max length of message extension data 


e Message extension data length 
e Message data pointer 
e Message data extension pointer 


e Message format information 


— If the message is not a return or return/transfer control message. 


- Compare data 


— Ifthe message is a return or return/transfer control message. 


- Return handler identifier 


- Reserved 


e Reserved (binary 0) 


Materialize Process Message (MATPRMSG) 


Bit 37 
Bit 38 
Bit 39 J 
Bits 40-63 
Char(1) 
Char(1) 
UBin(2) 
Char(1) 
Char(1) 

Bin(2) 

Char(7) 
Char(1) 

Bin(4)' 

Bin(4) 

Bin(4)' 

Bin(4) 

Space pointer’ 
Space pointer’ 
Char(32) 


Char(32) 


System or 
Procedure pointer 


Char(16) 
Char(32) 


The first 4 bytes of the message template identify the total number of bytes provided for use the 
instruction. This number is supplied as input to the instruction and is not modified by the instruction. 
A number less than 160 causes the materialization length (hex 3803) exception. 


Message type 


This value determines the type of the message. The type of message determines which 


message status values have meaning. 


The following message status are valid for all informational message types. 


e Log Message 
e Reply 
e Inquiry 


The following message status are valid for a message type of Exception. 


« Log Message 


1 Input to the instruction 
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Retain 

Action pending 
Invoke- PDEH 
Inquiry 

Reply 


The following message status are valid for a message type of return or return/transfer 
control. 


Action pending 


The following describes each message type in detail. 


informational 0 - There are no special requirements as to what message status contains 
or what the Target Invocation pointer actually identifies. 


informational 1 - There are no special requirements as to what message status contains 
or what the Target Invocation pointer actually identifies. 


Exception - This type of message has an interrupt cause for the interrupeted invocation. 


Return - This message type indicates that a return handler will be invoked if the target 
invocation is exited for any reason other than Transfer Control (XCTL). In the case of 
XCTL, the message is preserved and associated with the transferred to invocation. 
Additionally, messages of this type interpret the message format information field to 
identify a program or procedure to be invoked as the return handler. 


Return/Transfer control - This message type indicates that a return handler is invoked 
when the target invocation is exited for any reason including XCTL. Additionally, mes- 
sages of this type interpret the message format information field to identify a program or 
procedure to be invoked as the return handler. 


Message severity 


A value indicating the severity of the message. 


Reply/inquiry message reference key 


If the message materialized is an inquiry message, that has been answered this is the 
message reference key of its reply message. 


lf the message materialized is a reply message, this is the message reference key of its 
inquiry message. 


This value only has meaning for exception, and informational messages. 


Message status mask 
A bit-significant value indicating the original status of the message. 


Log message status. If this bit is TRUE, then the message is queued to the Process 
Message Log until it is explicitly removed. 


Inquiry status. If this bit is TRUE , then this message will accept a rep/y message. 


Reply status. If this value is TRUE , then this message is a Reply to an inquiry message. 
The reply message reference key is used to identify the message for which the message 
was replied. 


Answered status. If this value is TRUE, then the message is a inquiry message for which 
a reply has been sent. The reply message reference key is used to identify the reply 
message. 


Retain status. If this bit is TRUE, then the message is kept even in the invocation 
message queue after the following message status bits are FALSE: Log, Message being 
processed, and Action pending 
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« .Action pending. status. If this bit is TRUE, this message represents an exception which 
is the current interrupt cause for the specified Source Invocation or else it is a Return or 
Return/Transfer Control message which has not yet been processed. 


« Invoke Process Default Exception Handler. This status only has meaning for exception 
messages. 


Interrupt class mask 
A bit-significant value indicating the cause of the interrupt. The MI user is allowed to use 


the machine-defined classes since machine-generated errors may be re-sent by the MI 
user. 


This value only has meaning for exception messages. 


Initial handler priority 


An unsigned eight-bit binary number which selects the initial interrupt handler priority. This 
value is within the range of of 64 - 255. 


This value only has meaning for exception messages. 


Exception ID 
A two-byte field that identifies the exception being defined by this message. 


This value only has meaning for exception messages. 


PDEH Reason Code 
A value defined by the user which indicates the type of processing to be attempted by the 
Process Default Exception Handler. 


This value only has meaning for exception messages. 


Compare data length 
A value indicating the number of bytes provided as compare data. 


This value only has meaning for exception messages. 


Message ID 
Specifies the message identifier of a message description whose predefined message is 


being sent. 


Max length of message data 
Input to the instruction that specifies the number of bytes supplied for the message data. 


The maximum value allowed is 65504. 


Message data length 


A value indicating the number of bytes of message data for this process message. 


Max length of message data extension 


Input to the instruction that specifies the number of bytes supplied for the message data 
extension. The maximum value allowed is 65504. 


Message data extension length 


A value indicating the number of bytes of message data extension for this process 
message. 


Message data pointer 
A pointer to the area to receive the message data. This field is ignored if the max length of 


message data field is zero. 


Message data extension pointer 
A pointer to the area to receive the message data extension. This field is ignored if the max 


length of message data extension field is zero. 


Message format information 
A 32 byte field that contains either compare data or two 16 bytes fields which contain infor- 


mation related to a return type message. 
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* If message type is not a return or return/transfer contro! message. this field is defined 
as compare data used to determine which exception handler is to given control. Up to 
32 bytes may be specified. 


* If message type is a return or return/transfer contro/ message, then the first 16 bytes of 
this field are defined as a system pointer to an program object, or else a procedure 
pointer to a New Model procedure. The last 16 bytes of the field are reserved for future 
use. 


This value is ignored if the message does not represent an exception, return or 
return/transfer control message. 


The template identified by operand 3 specifies the source invocation of the message. This operand can 
be null (which indicates the requesting invocation is to be used for the Source Invocation) or specify 
either an Invocation pointer to an invocation, a null pointer (which indicates the current invocation), or 
a pointer to a Process Queue Space. It must be 16-byte aligned with the following format. 


Source invocation offset Bin(4) 

Originating invocation offset Bin(4) 

Invocation range Bin(4) 

Reserved (binary 0) Char(4) 

Source invocation/Process Queue Space pointer Invocation/System 
pointer 

Reserved (binary 0) ‘Char(16) 


Source invocation offset 


A signed numerical value indicating an invocation relative to the invocation located by the 
source invocation pointer. A value of zero denotes the the invocation addressed by the 
source invocation pointer, with increasingly positive numbers denoting increasingly later 
invocations in the stack, and increasingly negative numbers denoting increasingly earlier 
invocations in the stack. If a Process Queue Space is specified as the message source, 
then the only valid values for this field are 0, -1 and -2. A value of -1 indicates to materi- 
alize from the external queue of the Process Queue Space. A Zero value indicates to mate- 
rialize from the message log of the Process Queue Space. A value of -2 indicates to 
attempt to locate the message using the message reference index supplied in operand 4 
without regard to the queue space queue that the message resides on. Only unanswered 
inquiry messages, return messages, and return/transfer control messages can be material- 
ized in thts fashion. Other values result in a scalar value invalid (hex 3203) exception being 
signaled. 


lf the invocation identified by this offset does not exist in the stack, a scalar value invalid 
(hex 3203) exception will be signaled. 


Originator invocation offset 


Specifies a displacement from the invocation executing this instruction and must be zero 
(which indicates the current invocation) or negative (which indicates an older invocation). 
The invocation identified is used as the source for all authorization checks (environment 
authority to an invocation or authority to a process queue space). If the originator invoca- 
tion offset is non-zero, then the invocation executing this instruction must be authorized to 
the originating invocation identified. 


If the invocation identified by this offset does not exist in the stack or the value is greater 
than zero, a scalar value invalid (hex 3203) exception will be signaled. 
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A signed numerical value indicating the number of invocations in the range in addition to 
the invocation identified by the Source invocation pointer. If a Process Queue Space pointer } 


is provided, this value must be Zero. 


The sign of the invocation range determines the direction of the additional invocations. A 
positive number specifies a range encompassing newer invocations, while a negative 


number specifies a range encompassing older invocations. 


It is not an error if this value specifies a range greater than the number of existing invoca- 
tions in the specified direction. The materialization will stop after the last invocation is 


encountered. 


Source invocation pointer 


An invocation pointer to an invocation. If null, then the current invocation is indicated. 


If the invocation identified does not exist in the stack or is invalid for this operation, an 


invalid invocation (hex 1603) exception will be signaled. 


Process Queue Space pointer 


A system pointer to a Process Queue Space object. 


The template identified by operand 4 must be 16-byte aligned. Following is the format of the message 


selection template: 


¢ Starting message reference index 


e Ending message reference index 
¢ Number of selection criteria 


e Reserved (binary Q) 


e Selected message reference index 


e Selected message count 
¢ Status change count 

¢ Moved message count 

¢ Selection criterion 


— Selection type 


hex 00 = Select based on message status 


hex 01 
hex 02 
hex 03 


hex 04 = Select based on activation group mark 


— Reserved (binary 0) 
— Selection action 


- Reject criterion 


0 = Select message if criterion is statisfied 
1 = Reject message if criterion is statisfied 


- Reject message 


2 Ignored by the instruction 
3 Output by the instruction 


Select based on message ID 
select based on interrupt class 


Select based on invocation mark 


Char(4) 

Char(4) 

Bin(2) 

Char(6) 

Char(4)3 ») 
Bin(4)3 

Bin(4)? 

Bin(4)? 

Char(32) 

Char(1) 


Char(1) 
Char(2) 
Bit 0 


Bit 1 
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- Reserved (binary 0) 
— Message type mask 


— Selection criterion information 


If the selection type is message status 


- Message status mask 
- Message status complement 


- Reserved (binary 0) 


If the selection type is message /D 


- Message ID 
- Reserved (binary 0) 


If the selection type is interrupt class 


- Interrupt class mask 
- Interrupt class complement 


- Reserved (binary 0) 


If the selection type is invocation mark 


- Invocation mark 


- Reserved (binary 0) 


Materialize Process Message (MATPRMSG) 


Do not reject message if criterion is not satisfied 
Reject message if criterion is not satisfied 


Bits 2-15 
Char(4) 
Char(24) 


Char(8) 
Char(8) 
Char(8) 


Char(7) 
Char(17) 


Char(8) 
Char(8) 
Char(8) 


UBin(4) 
Char(20) 


If the selection type is activation group mark 


- Activation group mark 


- Reserved (binary 0) 


Starting and ending message reference index 


UBin(4) 
Char(20) 


Messages in the specified range of index values are examined either until one of the 
selection criteria has been satisfied or all queues specified have been searched. The direc- 
tion of search is determined by the relative values of Starting Message Reference Index and 
Ending Message Reference Index. If the former value is smaller, then the search direction 
is in numerically (and chronologically) increasing order, while if the latter value is smaller 
the search direction is in the opposite direction. 


Messages are examined starting with the message identified by starting message reference 
index, or if no such message exists in the queue, starting with the closest existing message 


in the direction of the search. 


lf operand 3 specifies a system pointer to a a queue space and a source invocation offset of 
-2, then the starting and ending message reference indices must be equal, otherwise a 
scalar value invalid (hex 3203) exception will be issued. 


Number of selection criteria 


A numerical value that specifies how many selection criteria fields are supplied. If number 
of selection criteria has a value of zero, then the first message in the index range will be 


materialized. 


Selected message reference index 


This value returns the message reference index of the message materialized. Zero is 
returned if no message satisfies the criteria. 
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Selected message count 
This value indicates the number of messages selected: zero for no messages found. one if 


a message was found. 


Selection criterion 
This field contains the data used to select messages from a queue space. There is a vari- 
able number of criteria present in the template (the number present is in the number of 
selection criteria field). Each selection criterion may select a message, reject it, or take no 
action. Successive selection criteria are applied to each message until it is selected or 
rejected, or until selection criteria have been exhausted (in which case selection is the 
default). 


Selection type 


This field indicates the format of the selection criterion and what field in the message is 
compared. 


Selection action 
A bit-significant value indicating what actions to perform during the selection criteria proc- 


essing. 


¢ Reject criterion - If this bit is TRUE, a message is rejected if the selection criterion is 
satisfied. If this bit is FALSE, then a message is selected when the selection criterion is 
satisfied. 


e Reject message - If this bit is TRUE, a message is rejected if the selection criteria is not 
satisfied. If this bit is FALSE, then a message is selected when the selection criteria not 
is satisfied. 


Message type mask 


A bit-significant value indicating types of messages that should be examined during 
selection criteria processing. The first 31 bits correspond to message types hex 00 through 
hex 1E respectively. The 32nd bit (bit 31) corresponds to all message types greater than hex 
1E. 


Message status mask and message status complement 


These are bit-significant values indicating the message status attributes that will allow a 
message to be selected. These values are used to test a message as follows: 


The message status complement is bit-wise exclusive-ORed with the message status value 
of a message. The result of this is then bit-wise ANDed with the message status mask. If the 
result is all FALSE bits, then the message does not satisfy this selection criterion. If the result 
is not ail FALSE, bits then the message satisfies the selection criterion. 


Message |D 
A character value that is compared to the message ID of a message. If the values are 


equal the selection is satisfied. 


Interrupt class mask and interrupt class complement 


These are bit-significant values indicating the interrupt class attributes that will allow a 
message to be selected. These values are used to test a message as follows: 


The interrupt class complement is bit-wise exclusive-ORed with the interrupt class value of a 
message. The result of this is then bit-wise ANDed with the interrupt class mask. lf the- 
result is all FALSE bits, then the message does not satisfy this selection criterion. If the result 
is not all FALSE bits, then the message satisfies the selection criterion. 


invocation mark 
A binary number that is compared to the invocation mark of a message. If the values are 
equal the selection is satisfied. 
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Activation group mark 
A binary number that is compared to the activation group mark of a message. if the values 


are equal the selection is satisfied. 


Authorization Required: The following algorithm is used to determine authorization. 


1. The invocation which invoked the MATPRMSG instruction must have authority to the invocation 
identified as the Source Invocation. 


2. The Originating Invocation must have authority to the invocation identified as the Source Invocation 
or to the invocation directly called by the Source invocation. 
lf any of the authority checks fail then a activation group access protection violation (hex 2C12) excep- 
tion will be signaled. 
e Operational 
— Operand 3 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 
— Operand 3 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 3 4 Other 
06 Addressing 

01 space addressing violation X X X X 

02 boundary alignment X X X X 

03 range X X X X 

06 optimized addressability invalid X X X X 
08 Argument/parameter 

01 parameter reference violation X X X X 
0A Authorization 

01 unauthorized for operation X X 
10 Damage encountered 

04 system object damage state X X X X X 

05 authority verification terminated due to damaged object X 

44 partial system object damage X X X X X 
1A Lock state 

01 invalid lock state X xX 
1C Machine-dependent exception 

03 machine storage limit exceeded X X 

04 object storage limit exceeded X 
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Exception 


20 


22 


24 


2C 


2E 


36 


46 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 abject destroyed 
03 object suspended 


07 authority verification terminated due to destroyed object 


_ Pointer specification 


01 pointer does not exist 
O02 pointer type invalid 


03 pointer address invalid object 


Program execution 


12 activation group access protection violation 


Resource control limit 


Of user profile storage limit exceeded 


Space management 
01 space extension/truncation 
Queue space management 


01 queue space not associated with the process 


Operands 
1 2 3 4 Other 
J 
x 
Xx 
X X X Xx 
X X X X 
X X X X 
X 
X X X X 
X X X X 
X 
X 
X 
X 
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Extended Function Instructions 


These instructions provide an extended set of functions which can be used to control and monitor the 
operation of the machine. Because of the more complicated nature of these instructions, they are 
more exposed to changes in their operation in different machine implementations than the basic func- 
tion instructions. Therefore, it is recommended that, where possible, programs avoid using these 
extended function instructions to minimize the impacts which can arise in moving to different machine 
implementations. 
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Chapter 16. Context Management Instructions €) 


This chapter describes the instructions used for context management. These instructions are in alpha- 
betic order. See Appendix A, “Instruction Summary,” for an alphabetic summary of all the instructions. 
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© Copyright |BM Corp. 1991, 1993 16-1 


Context Management Instructions 


Chapter 16. Context Management Instructions 16-2 


Materialize Context (MATCTX) 


Materialize Context (MATCTX) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 | 
0133 Receiver Permanent Materialization 

context, temporary options 

context, or 


machine context 


Operand f: Space pointer. 
Operand 2: System pointer or null. 


Operand 3: Character scalar. 


ILE access 
MATCTX ( 
receiver : space pointer 
var context : system pointer; OR 


null operand; 
var materialization options : aggregate 


) 


Description: Based on the contents of the materialization options specified by operand 3, the symbolic 
identification and/or system pointers to all or a selected set of the objects addressed by the context 


specified by operand 2 are materialized into the receiver specified by operand 1. If operand 2 is null, 


then the machine context is materialized. J 
The materialization options operand has the following format: 
* Materialization control Char(2) 
— Information requirements (1 = materialize) Char(1) 
- Reserved (binary 0) Bits 0-3 
- Extended context attributes Bit 4 
- Validation Bit 5 
Q = Validate system pointers 
1 = No validation 
- System pointers Bit 6 
- Symbolic identification | Bit 7 
— Selection criteria Char(‘1) 
- Reserved (binary 0) Bits 0-2 
- Modification date/time selection Bit 3 
0 = Do not select by modification date/time 
1 = Select by modification date/time 
- Object ID selection Bits 4-7 


* Hex O0—AIl entries 


« Hex 1—Type code selection 


e Hex 2—Type code/subtype code selection 
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e Hex 4—Name selection 
* Hex 5—Type code/name selection 
« Hex 6—Type code/subtype code/name selection 


* Hex E—Context entries collating at and above the specified Type code/subtype 
code/name selection 


e Length of name to be used for search argument Bin(2) 

e Type code Char(1) 
« Subtype code Char(1) 
« Name Char(30) 
e Timestamp Char(8) 


The materialization control information requirements field in the materialization options operand speci- 
fies the information to be materialized for each selected entry. Symbolic identification and system 
pointers identifying objects addressed by the context can be materialized based on the bit setting of 
this parameter. 


If the information requirements field is binary 0, the context attributes are materialized with no context 
entries. In this case, the selection criteria field is meaningless. 


If the information requirements field is set to just return the extended context attributes, the context 
attributes and extended attributes are materialized with no context entries. In this case, the selection 
criteria field is meaningless. 


If the validation attribute indicates no validation is to be performed, no object validation occurs and a 
significant performance improvement results. 


When no validation occurs, some of the following pointers may be erroneous: 
¢« Pointers to destroyed objects 
e« Pointers to objects that are no longer in the context 


¢ Multiple pointers to the same object 


The materialization control selection criteria field specifies the context entries from which information 
is to be presented. The type code, subtype code, and name fields contain the selection criteria when a 
selective materialization is specified. 


When type code or type/subtype codes are part of the selection criteria, only entries that have the 
specified codes are considered. When a name is specified as part of the selection criteria, the N char- 
acters in the search criteria are compared against the N characters of the context entry, where N is 
defined by the length of name to be used for search argument field in the materialization options. The 
remaining characters (if any) in the context entry are not used in the comparison. 


Selection criteria value hex 00, when the number of bytes provided in the receiver does not allow for 
materialization of at least one context entry, requests that as much of the context attributes as will fit 
be materialized into the receiver and that an estimate of the the byte size correlating to the full list of 
context entries currently in the context be set into the number of bytes available for materialization 
field of the receiver. This capability of requesting an estimate of the size of a full materialization of the 
context provides a low overhead way of getting a close approximation of the amount of space that will 
be needed for an actual materialize of all context entries. This approximation may be either high or 
low by a few entries due to abnormal system terminations. 
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Selection criteria value hex 00, when the number of bytes provided in the receiver allow for 

materialization of at least one context entry, and values hex 01 through hex 06 request that all context 

entries matching the associated type code/subtype code/name criteria be materialized into the . 
receiver. The number of bytes available for materialization field is set with the byte size correlating to J 
the full list of context entries that matched the selection criteria whether or not the receiver provided 

enough room for the full list to be materialized. 


selection criteria value hex OE requests that as many context entries as will fit which collate at or 
higher (are equal to or greater) than the specified type code/subtype code/name criteria be material- 
ized into the receiver. The number of bytes available for materialization field is set with the byte size 
correlating to the list of context entries that were actually materialized into the receiver rather than the 
full list that may have been available in the context. 


If modification date/time selection is specified, then entries are selected according to the time of last 
modification in addtiion to any object identification selection specified. The timestamp in the 
materialization control is used to determine which entries will be selected. Entries with modification 
timestamps greater than or equal to the timestamp specified in the control will be selected. Besides 
the additional selection done as above, the materialize will work the same as specified in the other 
controls. 


Programming note: |f the specified timestamp is for a date/time earlier than the date/time currently 
associated with the changed object list, all objects in the context will be inspected for their modification 
date. This may degrade system performance. 


The tormat of the materialization (operand 1) is as follows: 


e Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) ( 
— Number of bytes available for materialization Bin(4) J 
e Context identification Char(32) 
— Object type Char(1) 
— Object subtype Char(‘) 
— Object name Char(30) 
« Context options Char(4) 
— xistence attributes Bit 0 
0 = Temporary 
1 = Permanent 
— Space attribute Bit 1 
0 = Fixed-length 
1 = Variable-length 
— Reserved (binary 0) Bit 2 
— Access group Bit 3 
O = Not a member of access group 
1 = Member of access group 
— Reserved (binary 0) Bits 4-31 
¢ Recovery options Char(4) 


— Automatic damaged context rebuild option 
0 = Do not rebuild at IMPL 


Bit 0 a 
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1 = Rebuild at IMPL 
Size of space 
Initial value of Space 
Performance class 


— Space alignment 


Bin(4) 
Char(1) 
Char(4) 
Bit O 


Materialize Context (MATCTX) 


O = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, this value must 


be specified for the performance class. 


1 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space as well as to allow proper alignment of input/output 


buffers at 512-byte alignments within the the space. 


— Reserved (binary 0) 


— Main storage pool selection 


0 = Process default main storage pool is used for object. 
1 = Machine default main storage pool is used for object. 


— Reserved (binary 0) 


— Block transfer on implicit access state 
modification 


Bits 1-4 
Bit 5 


Bit 6 
Bit 7 


0 = Transfer the minimum storage transfer size for this object. This value is 1 storage unit. 
1 = Transfer the machine default storage transfer size. This value is 8 storage units. 


— Reserved (binary 0) 
Reserved (binary 0) 
Reserved (binary 0) 
Access group 
Extended Context Attributes (if requested) 
— Changed object list 
0 - A changed object list does not exist 
1 - A changed object list does exist. 
— Useable changed object list 
0 - Changed object list is in a useable state 
1 - Changed object list is not in a useable state 
— Reserved (binary 0) 
Reserved (binary 0) 
Current timestamp 
Context entry (repeated for each selected entry) 
— Object identification (if requested) 
- Type code 
- Subtype code 
- Name 


— Object pointer (if requested) 


Bits 8-31 
Char(7) 
Char(16) 
System pointer 
Char(1) 

Bit O 


Bit 1 


Bit 2-7 
Char(7) 
Char(8) 
Char(16-48) 
Char(32) 
Char(1) 
Char(1) 
Char(30) 


system pointer 
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The first 4 bytes of the materialization output identify the total number of bytes provided for use by the 
instruction. This value is supplied as input to the instruction and is not modified by the instruction. A 
value of less than 8 causes the materialization length (hex 3803) exception to be signaled. The instruc- 
tion materializes as many bytes and pointers as can be contained in the receiver. If the byte area 
identified by the receiver is greater than that required to contain the information requested for 
materialization, the excess bytes are unchanged. No exceptions are signaled in the event that the 
receiver contains insufficient area for the materialization, other than the materialization length (hex 
3803) exception described above. 


J 


See the Create Context (CRTCTX) for a description of the common object creation fields. 


The context entry object identification information, if requested by the materialization options field, is 
present for each entry in the context that satisfies the search criteria. If both system pointers and 
symbolic identification are requested by the materialization options field, the system pointer imme- 
diately follows the object identification for each entry. 


The order of the materialization of a context is by object type code, object subtype code, and object 
name, all in ascending sequence. 


Authorization Required 
e Retrieve 


— Operand 2 


Lock Enforcement 


e Materialization 


— Operand 2 J 


Exceptions 
Operands 

Exception 1 2 3 Other 
06 Addressing 

01 Space addressing violation X X X 

02 Boundary alignment X X X 

03 Range Xx X X 

06 Optimized addressability invalid X X X 
08 Argument/parameter 

01 Parameter reference violation X X X 
0A Authorization 

01 Unauthorized for operation X 
10 Damage encountered 


02 Machine context damage state 
04 System object damage state 


05 authority verification terminated due to damaged object 


x 

x< 

x< 
x KK OK 


44 Partial system object damage X X X 


1A Lock state 2 


01 Invalid lock state X 
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Operands 
Exception 1 2 3 Other 
1c Machine-dependent exception 


03 Machine storage limit exceeded X X 


20 Machine support 
02 Machine check Xx 
03 Function check 4 


22 Object access 
01 Object not found X X X 
02 Object destroyed 
03 Object suspended X X X 
07 authority verification terminated due to destroyed object X 


x< 
x 
~< 


08 object compressed X 


24 Pointer specification 


01 Pointer does not exist X 4 X 


x 
* 


02 Pointer type invalid X 


03 Pointer addressing invalid object X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
02 Scalar attributes invalid X 


03 Scalar value invalid x 


36 Space management 


01 space extension/truncation X 


38 Template specification 


03 Materialization length exception X 
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Chapter 17. Authorization Management Instructions 


This chapter describes the instructions used for authorization management. These instructions are in 
alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 


Materialize Authority (MATAU) ......0.0.. 0.000000 0 17-3 
Materialize Authority List (MATAL) .......0 2.00.00 0. 0 0 ee ee 17-7 
Materialize Authorized Objects (MATAUOBJ)  ...... 2. 17-12 
Materialize Authorized Users (MATAUU) ........0 00... . 0... ee ee 17-20 
Materialize User Profile (MATUP) ........0.. 0.0. 000 ee ee 17-25 
TESUAULHOFIIY (TESTA), sice ee ied eek ea BE ee et Pe SS OO Se ew ek 17-29 
Test Extended Authorities (TESTEAU)  ..........0 2.0.00 00.000. ee ee es 17-34 
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Materialize Authority (MATAU) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0153 Receiver System object User profile or 
Source Template 


Operand 1: Space pointer. 
Operand 2: System pointer. 


Operand 3: System pointer or Space pointer data object or null. 


ILE access 
MATAU ( 
receiver : space pointer; 
var system object : system pointer; 


var user profile _or_source_ template : system pointer OR 
space pointer OR 
null operand 


Description: This instruction materializes the specific types of authority for a system object available 
to the specified user profile. The private authorization that the user profile specified by operand 3 has 
to the permanent system object specified by operand 2, and the object’s public authorization is materi- 
alized in operand 1. If operand 3 is null, then only the object’s public authorization is materialized, and 
the private authorization field in the materialization is set to binary 0. 


Except for certain special cases, the authority to be materialized is determined by first checking for 
direct authority to the object itself, then checking for indirect authority to the object through authority to 
an authorization list containing the object. The first source of authority found is materialized and the 
source is indicated in the materialization. 


The special case of the operand 3 user profile having all object special authority overrides any explicit 
private authorities that the user profile might hold to the object or its containing authorization list and 
results in a materialization showing that the profile holds all private authorities directly to the object. 


The special case of the operand 2 object being in an authorization list which has the override specific 
object authority attribute in effect results in the authorization or lack of authorization held to the 
authorizaiton list completely overriding the explicit private authorities that the user profile might hold 
to the object. This case results in a materialization showing that the profile has just the private author- 
ities it holds or doesn’t hold to the authorization list. That is, if the user profile has private authority to 
the object, but doesn’t have private authority to the authorization list, the materialization will show that 
the user does not have any private authority to the object. Similarly, if the user profile has both private 
authority to the object and to the authorization list, the materialization will show that the user has only 
the private authority through the authorization list. If operand 3 is null, then only the object’s public 
authorization is materialized, and the private authorization field in the materialization is set to binary 
zeros. 


Operand 3 may be specified as a a system pointer which directly addresses the user profile to be 
checked as a source of authority or as a space pointer to a source template which identifies the source 
user profile. Specifying a template allows for additional controls over how the materialize operation is 
to be performed. The format of the source template is the following: 


*« Source flags Char(2) 
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Ignore all object special authority 


0 = No 
1 = Yes 


Reserved (binary 0) 


« Reserved (binary 0) 


e« User profile 


Materialize Authority (MATAU) 


Bit 0 


Bit 1-15 
Char(14) 


System pointer 


The ignore all object special authority source flag specifies whether or not that special authority is to 
be ignored during the materialize operation. When yes is specified, just the explicitly held private 
authority that the specified user profile holds either directly to the object or indirectly to an authori- 
zation list containing the object will be materialized. When no is specified, the authority provided by 
all object special authority, if held by the source user profile, is included and results in a 
materialization showing that the profile holds all private authorities directly to the object. No is the 


default for this flag value when the source template is not specified. 


The user profile field specifies the user profile to be checked as a source of authority. 


The format of the materialization (operand 1) is as follows: 


e Materialization size specification 


¢ Private authorization (1 = authorized) 


Number of bytes provided for materialization 


Number of bytes available for materialization 
(contains a value of 16 for this instruction) 


Object control 

Object management 
Authorized pointer 
Space authority 
Retrieve 

Insert 

Delete 

Update 

Ownership (1 = yes) 
Excluded 

Authority List management 


Reserved (binary 0) 


¢« Public authorization (1 = authorized) 


Object control 
Object management 
Authorized pointer 
Space authority 
Retrieve 

Insert 


Delete 


Char(8) 
Bin(4) 
Bin(4) 


Char(2) 
Bit O 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bit 11-15 
Char(2) 
Bit O 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
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— Update Bit 7 
— Reserved (binary 0) Bit 8 
— Excluded Bit 9 ») 
— Authority List management Bit 10 
— Reserved (binary 0) Bit 11-15 
e Private authorization source UBin(2) 
0 = authority to object 
1 = authority to authorization list 
¢ Public authorization source UBin(2) 
0 = authority from object 
1 = authority from authorization list 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception. 


The second 4 bytes of the materialization identify the total number of bytes available to be materialized 
(16 for this instruction). The instruction materializes as many bytes as can be contained in the area 
specified as the receiver. If the byte area identified by the receiver is greater than that required to 
contain the information requested, then the excess bytes are unchanged. No exceptions (other than 
the materialization !ength exception) are signaled in the event that the receiver contains insufficient 
area for the materialization. ) 


Any of the four authorizations- retrieve, insert, delete, or update-constitute operational authority. 


2 
If this instruction references a temporary object, all public authority states are materialized. Private 
authority states are not materialized. 


Authorization Required 
e Operational 

— QOperand 3 
¢« Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialize 

— Operand 2 

— Operand 3 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation Xx x X wa 
02 boundary alignment 4 X X 
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Exception 


08 


0A 


10 


1C 


20 


22 


24 


2E 


36 


38 


03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 

02 machine context damage state 

04 system object damage state 

05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Materialize Authority (MATAU) 


Operands 
1 2 
X x 
X X 
X X 

X 
X X 
X X 

X 
X X 
X X 
X X 
X X 
X X 

X 
X 


x 


~< 


x< 


Other 


x KX XK XK 
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Materialize Authority List (MATAL) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 J 
01B3 Receiver Authorization List Materialization 
Options 


Operand 1: Space pointer. 
Operand 2: System pointer. 


Operand 3: Space pointer. 


ILE access 
MATAL ( 
receiver : space pointer 
var authorization list : system pointer 


materialization options : space pointer 


Description: Based on the contents of the materialization options specified by operand 3, the symbolic 
identification and/or system pointers to all or a selected set of the objects contained in the authori- 
zation list specified by operand 2 are materialized into the receiver specified by operand 1. 


The materialization options operand has the following format: 


« Materialization control Char(2) S' 
— Information requirements Char(1) 
12= Materialize count of entries matching the criteria. 
22= #Materialize identification of entries matching the criteria and return information using 
short description format 
32= #Materialize identification of entries matching the criteria and return information using 
long description format 
— Selection criteria Char(1) 
00 = All authorization list entries 
01 = Type code selection 


02 = Type code/subtype code selection 


« Reserved (binary 0) Bin(2) 

¢« Type code Char(‘1) 
« Subtype code Char(‘) 
« Reserved (binary 0) Char(30) 


The information requirements field specifies the type of materialization, just a count of entries, short 
descriptions, or long descriptions, which is being requested. 


The selection criteria field specifies the criteria to be used in selecting the authorization list entries for 


which information is to be presented. The type code and subtype code fields contain the selection 2 | 
criteria when a selective materialization is specified. 
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When type code or type/subtype codes are part of the selection criteria, only entries that have the 


Specified codes are considered. 


= The format of the materialization (operand 1) is as follows: 


If no description (information requirements = hex 12) is requested in the materialization options 


Materialization size specification 
— Number of bytes provided for materialization 
— Number of bytes available for materialization 
Authorization List identification 
— Object type 
— Object subtype 
— Qbject name 
Authorization List creation options 
— Existence attributes 
1 = Permanent (always permanent) 
— Space attribute 


0 = Fixed length 
1 = Variable length 


— Reserved (binary 0) 

Reserved (binary 0) . 

Size of space 

Initial value of space 

Performance class 

Reserved 

Context 

Reserved 

Authorization List attributes 

— Override specific object authority 


0 = No 
1 = Yes 


— Reserved (binary 0) 
Reserved (binary 0) 

Entries header 

— Number of entries available 


— Reserved 


Char(8) 
Bin(4) 
Bin(4) 
Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(4) 
Bit 0 


Bit 1 


Bit 2-31 


~ Char(4) 


Bin(4) 

Char(1) 
Char(4) 

Char(7) 

System pointer 
Char(16) 
Char(4) 

Bit 0 


Bit 1-31 
Char(28) 
Char(16) 
UBin(4) 
Char(12) 


Materialize Authority List (MATAL) 


parameter, the above constitutes the information available for materialization. If a description (short or 
long) is requested by the materialization options operand, a description entry is present (assuming a 


sufficient size receiver) for each object materialized into the receiver. Either of the following entry 
formats may be selected. 


e Short description entry 
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— Type code 
— Subtype code 
— Reserved 
— System object 
e Long description entry 
— Type code 
— Subtype code 
— Object name 
— Reserved 
— System object 
— Object owning user profile 
— Context 
- Type code 
- Subtype code 
- Context name 


- Context pointer 


Materialize Authority List (MATAL) 


Char(1) 
Char(1) 
Char(14) J 
System pointer 
Char(128) 
Char(1) 
Char(‘1) 
Char(30) 
Char(16) 
System pointer 
System pointer 
Char(48) 
Char(1) 
Char(1) 
Char(30) 


System pointer 


The first four bytes of the materialization output identify the total number of bytes provided for use by 
the instruction. This value is supplied as input to the instruction and is not modified by the instruction. 
A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- J 
ized. The instruction materializes as many bytes and pointers as can be contained in the receiver. If 

the byte area identified by the receiver is greater than that required to contain the information 

requested for materialization, the excess bytes are unchanged. No exceptions are signaled in the 

event that the receiver contains insufficient area for the materialization, other than the materialization 


length (hex 3803) exception signaled above. 


Refer to the Create Authorization List instruction for a discussion of the creation attributes materialized 


in the above template. 


The number of entries available field specifies the number of authorization list entries which satisfied 
the selection criteria and were therefore materialized. A value of zero indicates no entries were avail- 


able. 


The object identification information (in the short and long description entries), if requested by the 
materialization options parameter, is present for each entry in the authorization list that satisfies the 


search criteria. 


The object pointer information (in the long description entry only), if requested by the materialization 
options parameter, is present for each entry in the authorization list that satisfies the search criteria. 


If the object addressed by the system pointer is not addressed by a context, the context type field is 
set to hex 00 or if the object is addressed by the machine context, the context type field is set to hex 
81. Additionally, in either of these cases, the context pointer is set to the system default “pointer does 


not exist” value. 


2 
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Materialize Authority List (MATAL) 


Authorization Required 
¢ Retrieve 


Operand 2 


Lock Enforcement 


e Materialization 


Operand 2 
Exceptions 
Operands 
Exception 1 2 3 Other 
06 addressing 


01 space addressing violation 
02 boundary alignment violation 


03 range 


x K KK 
x KK XK 
x KK XK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage X X 


x 


05 authority verification terminated due to damaged object 


44 partial system object damage xX 


1A Lock state 
01 invalid lock state X 


1c Machine dependent exception 


03 machine storage limit exceeded X X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X X 
02 object destroyed 
03 object suspended X X X 
07 authority verification terminated due to destroyed object X 


*< 
x 
x< 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X X Xx 
02 pointer type invalid X X Xx 
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Materialize Authority List (MATAL) 


Operands 
Exception 1 2 3 Other 
03 pointer addressing invalid object X 
2E Resource control limit J 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 scalar type invalid xX X X 
02 scalar attributes invalid X 


03 scalar value invalid 4 


36 Space management 


01 space extension/truncation X 


38 Template specification 


03 materialization length xX 


CC 
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Materialize Authorized Objects (MATAUOBJ) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
013B Receiver User profile Materialization 
options/template 


Operand 1: Space pointer. 
Operand 2: System pointer. 


Operand 3: Character scalar (fixed length). 


ILE access 
MATAUOBJ ( 
receiver : space pointer; 
var user profile : system pointer; 


var materialization_options : aggregate 


Description: This instruction materializes the identification and the system pointers to all or selected 
system objects that are privately owned and/or authorized by a specified user profile. For the user 
profile (operand 2), the materialization options (operand 3) specify object selection criteria and the 
format and location of the object materialization data. The receiver space (operand 1) always indicates 
the number of objects materialized, and contains the object materialization data unless the 
materialization options specify an independent index to contain the data. 


When the high-order bit of the materialization options is off, operand 3 is viewed as a Char(1) scalar. 
This option does not permit object selection by type and subtype, does not allow a continuation point to 
be specified, and returns all object materialization data in the receiver (operand 1). Following are the 
valid operand 3 values which may be used with the short template header format (operand 1): 


Value (hex) Meaning 


11 Materialize count of owned objects. 

12 Materialize count of authorized objects. 

13 Materialize count of all authorized and owned objects. 

21 Materialize identification of owned objects using short description entry format. 

22 Materialize identification of authorized objects using short description entry format. 

23 Materialize identification of ail authorized and owned objects using short description 
entry format. 

31 Materialize identification of owned objects using long description entry format. 

32 Materialize identification of authorized objects using long description entry format. 

33 Materialize identification of all authorized and owned objects using long description 


entry format. 


Following are the valid operand 3 values which may be used with the long template header format 
(operand 1): 
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Value (hex) Meaning 


51-53 These long template header materialization options are the same as the short template 
header materialization options 11-13 (hex). ) 
61-63 These long template header materialization options are the same as the short template 


header materialization options 21-23 (hex). 


71-73 These long template header materialization options are the same as the short template 


header materialization options 31-33 (hex) except that the context extension is material- 
ized for each object as well. 


When the high-order bit of the materialization options is on, operand 3 is viewed as variable-length, 
must be 16-byte aligned in the space, and has the following format: 


Materialization options Char(1) 


Valid values are hex 91-93, A1-A3, B1-B3, D1-D3, E1-E3, and F1-F3. They have the same meanings 
as the corresponding values hex 11 through 73. 


Materialization flags Char(1) 
— Restrict information dcope Bit 0 


This is an input bit which only has meaning when materialization data is being returned in the 
operand 1 receiver template. When there is more data to be materialized than can be con- 
tained in the template, then when this bit is on, the number of bytes available for 
materialization, the number of objects owned by the user profile, and the number of objects pri- 
vately authorized by the user profile output fields are restricted to reflect only the information 
returned in the template; when off, the output fields reflect the total amount of materialization 
data available, even though the template may not be large enough to contain it all. 

— More materialization data available Bit 1 ) 
This output bit has meaning only when materialization data is being returned in the operand 1 
receiver template. When on, it indicates that objects exist beyond those for which 
materialization data was returned in the template; when off it indicates the end of the objects 


was reached. 
— Continuation point specified Bit 2 


This is an input bit. When on, it indicates that a continuation point is specified in the continua- 
tion point field; when off, continuation processing is ignored. 


— Reserved (binary 0) Bits 3-7 
Reserved (binary 0) Char(30) 
Independent Index pointer system pointer 


If the pointer does not exist, the instruction returns all object materialization data in the receiver 
(operand 1). Otherwise it returns only the template header in the receiver and returns the object 
materialization data in the independent index. 


Continuation point Char(16) or 
system pointer 


If the continuation point specified bit is on, when the instruction begins, if this field contains a 
system pointer or the storage form of a system pointer, then materialization data is returned for 
objects found in the profile following the object identified by the continuation point; otherwise, 
materialization data is returned beginning with the object which is logically first. 


Object type/subtype range array Bin(2) dimension ; 
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Indicates the number of object type/subtype ranges specified in the array immediately following. If 
zero. objects of all types and subtypes are materialized. If larger than zero. only objects included 
in one or more of the type/subtype ranges specified in the array are materialized. 


¢ Object type/subtype array n * Char(4) 


An array of object type/subtype ranges qualifying the objects materialized. Each array element 
represents a range of object type/subtypes and has the following format: 


— Start of range Char(2) 
- Object type code Char(1) 
- Object subtype code Char(‘) 
— End of range Char(2) 
- Object type code Char(1) 
- Object subtype code Char(1) 


All materialization options for owned objects with descriptions (hex 21, 23, 31, 33, 61, 63, 71, 73, A1, A3, 
B1, B3, E1, E3, F1, and F3) also verify the user profile’s storage utilization, unless the extended form of 
operand 3 is used and a valid continuation point is specified. 


The order of materialization is owned objects (if requested by the materialization options operand) fol- 
lowed by objects privately authorized to the user profile (if requested by the materialization options 
operand). No authorizations are stored in the system pointers that are returned. 


The template identified by operand 1 must be 16-byte aligned in the space. For options hex 11 through 
hex 33 and hex 91 through hex B3, the short template header is materialized. It has the following 
format: 


¢ Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Number of objects owned by user profile Bin(2) 

e Number of objects privately Bin(2) 
authorized to user profile 

¢ Reserved (binary 0) Char(4) 


For options hex 51 through 77 and hex D1 through hex F7, the long template header is materialized. It 
has the following format: 


¢ Materialization size specification ; Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

¢ Number of objects owned by user profile Bin(4) 

e Number of objects privately Bin(4) 


authorized to user profile 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
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receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
the materialization. If the restrict information scope flag is 1, then the field contains the number of 
bytes materialized, rather than the number of bytes available to be materialized. 


If the restrict information scope flag is 1, then the number of objects owned by user profile and the 
number of objects privately authorized by user profile fields reflect the number of objects for which 
complete materialization data is returned, rather than the total number of such objects. 


If no description is requested in the materialization options field, the above constitutes the information 
available for materialization. If a description (short, long, or long with context extension) is requested 
by the materialization options field, a description entry is present for each object materialized into the 
receiver (assuming it is of sufficient size) or into the independent index. Object materialization data is 
in one of the following formats depending on the materialization options and the object into which it is 
materialized: 


Short description entry materialized 
into receiver 


Object type code 
Object subtype code 
Private authorization 
Reserved (binary 0) — 
Object pointer 


Long description entry materialized 
into receiver 


Object type code 
Object subtype code 
Object name 

Private authorization 
Public authorization 
Reserved (binary 0) 
Object pointer 


Long description entry with context 
extension materialized into receiver 


Object type code 
Object subtype code 
Object name 

Private authorization 
Public authorization 
Reserved (binary OQ) 
Object pointer 
Context type code 
Context subtype code 


Context name 


Char(32) 


Char(‘) 
Char(1) 
Char(2) 
Char(12) 

| System pointer 
Char(64) 


Char(1) 

Char(1) 
Char(30) 
Char(2) 
Char(2) 
Char(12) 
System pointer 
Char(112) 


Char(1) 
Char(1) 
Char(30) 
Char(2) 
Char(2) 
Char(12) 
System pointer 
Char(1) 
Char(1) 
Char(30) 
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Materialize Authorized Objects (MATAUOB4J) 


— Context pointer system pointer 


short description entry materialized Char(32) 
into independent index 


— Entry type code Char(1) 


hex 40 = Owned object 
hex 80 = Authorized object 


— Object type code Char(1) 

— Object subtype code Char(1) 

— Private authorization Char(2) 

— Reserved (binary 0) Char(11) 

— Qbject pointer System pointer 
Long description entry materialized Char(64) 

into independent index 

— Entry type code Char(1) 


hex 40 = Owned object 
hex 80 = Authorized object 


— Object type code Char(1) 
— Object subtype code Char(1) 
— Object name ‘Char(30) 
— Private authorization Char(2) 
— Reserved (binary 0) Char(2) 
— Public authorization Char(2) 
— Reserved (binary 0) Char(9) 
— Object pointer System pointer 
Long description entry with context Char(112) 
extension materialized into independent index 

— Entry type code Char(‘1) 


hex 40 = Owned object 
hex 80 = Authorized object 


— Context type code Char(‘) 
— Context subtype code Char(‘1) 
— Context name Char(30) 
— Object type code Char(‘1) 
— Object subtype code Char(‘1) 
— Object name Char(30) 
— Private authorization Char(2) 
— Reserved (binary 0) Char(2) 
— Public authorization Char(2) 
— Reserved (binary 0) Char(Q9) 
— Object pointer System pointer 
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— Context pointer System pointer 
Following is the format of the authorization information: 

¢ Private authorization Char(2) J 
(1 = authorized) 
— Object Control Bit 0 
— Object Management Bit 1 
— Authorized Pointer Bit 2 
— Space Authority Bit 3 
— Retrieve Bit 4 
— Insert Bit 5 
— Delete Bit 6 
— Update Bit 7 
— Ownership (1 = yes) Bit 8 
— Excluded Bit 9 
— Authority List management Bit 10 
— Reserved (binary 0) Bits 11-15 

e Public authorization (1 = authorized) _Char(2) 
— Object Control Bit 0 
— Object Management Bit 1 
— Authorized Pointer Bit 2 J 
— Space Authority Bit 3 
— Retrieve Bit 4 
— Insert Bit 5 
— Delete Bit 6 
— Update Bit 7 
— Reserved (binary 0) Bit 8 
— Excluded Bit 9 
— Authority List management Bit 10 
— Reserved (binary 0) Bits 11-15 


When context information is materialized, if the object addressed by the system pointer is not 
addressed by a context, the context type field is set to hex 00 or if the object is addressed by the 
machine context, the context type field is set to hex 81. Additionally, in either of these cases, the 
context pointer is set to the system default pointer does not exist value. 


When the more materialization data available flag is 1, the pointer to the object within the last entry in 

the operand 1 receiver template may be specified as the continuation point on a subsequent invocation 

of this instruction, to cause materialization to continue, starting with the “logically next” object. To 

determine whether the continuation point is within the owned or authorized objects, the ownership bit 

in the private authorizations of the last materialized object may be tested. This instruction does not 

guarantee an atomic snapshot of the user profile across a continuation request. a 


The following considerations apply when object materialization data is returned in an independent 
index: 
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system pointers returned in index entries are not set unless the index is created to contain both 
pointer and scalar data. 


Entry data may be truncated or padded on the right with hex zeroes to conform to the index’s key 
and/or fixed entry lengths. 


An entry is added to the index for each qualifying object. Previously existing entries which are 
thereby duplicated are replaced. 


In order to ensure that index entries inserted within the same execution of this instruction are not 
duplicates of each other, the /ndex entry length (if fixed) and key length (if Keyed) must be suffi- 
ciently large to include the object pointer within the entry data. 


Authorization Required 


e Operational 


— Operand 2 

Retrieve 

— Contexts referenced for address resolution 
— Operand 2 if materializing owned objects 
Insert 


— Independent index if identified by operand 3 


Lock Enforcement 


t 


Materialize 
— Contexts referenced for address resolution 


— Operand 2 if materializing owned objects 


© Modify 


— Independent index if identified by operand 3 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X X 
03 range X X X 
08 Argument/parameter 
01 parameter reference violation X X X 
0A Authorization 
01 unauthorized for operation X X 
10 Damage encountered 
02 machine context damage state X 
04 system object damage state X X X X 
Cc 05 authority verification terminated due to damaged object X X 
44 partial system object damage xX X X X 
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Exception 


1A 


1Cc 


20 


22 


24 


2E 


32 


36 


38 


Lock state 


01 invalid lock state 


Machine-dependent exception 
03 machine storage limit exceeded 


04 object storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

04 object not eligible for operation 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 


03 materialization length exception 


Operands 
1 2 
X 
X X 
X X 
X 
X X 
X : X 
X X 
X 
X 


»~< 


Other 
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Materialize Authorized Users (MATAUU) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 


0143 Receiver System object Materialization 
options 


Operand 1: Space pointer. 
Operand 2: System pointer. 


Operand 3: Character(1) scalar (fixed-length). 


ILE access 
MATAUU ( 
receiver : Space pointer; 
var system object : system pointer; 


var materialization_ options : aggregate 


Description: The instruction materializes the authorization states and the identification of the user 
profile(s). The materialization options (operand 3) for the system object (operand 2) are returned in the 
receiver (operand 1). The materialization options for operand 3 have the following format: 


‘Value (Hex) Meaning 


11 Materialize public authority. 

12 Materialize public authority and number of privately authorized profiles. 

21 Materialize identification of owning profile using short description entry format. 

22 Materialize identification of privately authorized profiles using short description entry 
format. 

23 Materialize identification of owning and privately authorized profiles using short 
description entry format. 

31 Materialize identification of owning profile using long description entry format. 

32 Materialize identification of privately authorized profiles using long description entry 
format. 

33 Materialize identification of owning and privately authorized profiles using long 


description entry format. 


The order of materialization is an entry for the owning user profile (if requested by the materialization 
options operand) followed by a list (0 to n entries) of entries for user profiles having private authori- 
zation to the object (if requested by the materialization options operand). The authorization field within 
the system pointers will not be set. 


The template identified by operand 1 must be 16-byte aligned in the space and has the following 
format: 


e Materialization size specification Char(8) 
— Number of bytes provided for materialization Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Public authorization Char(2) 
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(1 = authorized) 


— Object control . Bit O 

— Object management Bit 1 

— Authorized pointer Bit 2 

— Space authority Bit 3 

— Retrieve Bit 4 

— Insert Bit 5 

— Delete Bit 6 

— Update Bit 7 

— Reserved (binary 0) Bit 8 

— Excluded Bit 9 

— Authority List management Bit 10 

— Reserved (binary 0) Bits 11-15 
e Number of privately authorized Bin(2) 

user profiles 
e Reserved (binary 0) Char(4) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by.the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
the materialization. 


If no description is requested by the materialization options field, the template identified by operand 1 
constitutes the information available for materialization. If a description (short or long) is requested by 
the materialization options field, a description entry is present (assuming there is a sufficient sized 
receiver) for each user profile materialized or available to be materialized into the receiver. Either of 
the following entry types may be selected. 


* Short description entry Char(32) 
— User profile type code Char(1) 
— User profile subtype code Char(1) 
— Private authorization Char(2) 

(1 = authorized) 
- Object control Bit 0 
- Object management Bit 1 
- Authorized pointer Bit 2 
- Space authority Bit 3 
- Retrieve Bit 4 
- Insert Bit 5 
- Delete Bit 6 
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Update 

Ownership (1 = yes) 
Excluded 

Authority List management 


Reserved (binary 0) 


Reserved (binary 0) 


User profile 


e Long description entry 


— 


User profile type code 


User profile subtype code 


User profile name 


Private authorization (1 = authorized) 


Object control 

Object management 
Authorized pointer 
Space authority 
Retrieve 

Insert 

Delete 

Update 

Ownership (1 = yes) 
Excluded 

Authority List Management 
Reserved (binary 0) 


Reserved (binary Q) 


User profile 


Materialize Authorized Users (MATAUU) 


Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bits 11-15 
Char(12) 
system pointer 
Char(64) 
Char(1) 
Char(1) 
Char(30) 
Char(2) 
Bit O 
Bit 1 
Bit 2 
Bit 3 
Bit 4 

Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bits 11-15 
Char(14) 


System pointer 


If this instruction references a temporary object, all public authority states are materialized. The pri- 
vately authorized user and owner profile(s) descriptions are not materialized (binary Q). 


Authorization Required 


e Retrieve 


Contexts referenced for address resolution 


« Object management or ownership 


e Authorization list management or ownership 


Operand 2 object (when object is not an authorization list) 


— Operand 2 object (when object is an authorization list) 
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Lock Enforcement 
« Materialize 


— Operand 2 J 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK OK 
x KK XK 
x KK XK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage state X xX X X 


x 


05 authority verification terminated due to damaged object 
44 partial system object damage X X X Xx J 


1A Lock state 


01 invalid lock state »« 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X X 
02 object destroyed 
03 object suspended X X X 


07 authority verification terminated due to destroyed object X 


>< 
>< 
< 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X xX X 
02 pointer type invalid X X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
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Operands 
Exception 1 2 3 Other 
03 scalar value invalid X 
36 Space management 
01 space extension/truncation X 
38 Template specification 
03 materialization length exception X 
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Op Code (Hex) 
013E 


Operand 2 
User profile 


Operand 1 
Receiver 


Operand ?: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATUP ( 
receiver 
var user_profile : 


) 


: space pointer; 
system pointer 


Materialize User Profile (MATUP) 


Description: The attributes of the user profile specified by operand 2 are materialized into the 


receiver specified by operand 1. 


The receiver identified by operand 1 must be 16-byte aligned in the space. The following is the format 


of the materialized information: 
e Materialization size specification 


Number of bytes provided for materialization 
— Number of bytes available for materialization 
e Object identification 

Object type 


Object subtype 


Object name 

« Object creation options 
— Existence attribute 

1 = Permanent 

space attribute 


0 = 
7 


Fixed-length 
Variable-length 


Reserved (binary 1) 


Reserved (binary 0) 


Initialize space 
— Reserved (binary 0) 
e Reserved (binary 0) 

e Size of space 

e Initial value of space 

* Performance class 

¢ Reserved (binary 0) 


e Reserved (binary 0) 


Char(8) 
‘Bin(4) 
Bin(4) 
Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(4) 
Bit 0 


Bit 1 


Bit 2 

Bits 3-12 
Bit 13 
Bits 14-31 
Char(4) 
Bin(4) 
Char(1) 
Char(4) 
Char(7) 
Char(16) 
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Reserved (binary 0) 


Privileged instructions 


(1 


= authorized) 


Create Logical Unit Description 
Create Network Description 

Create Controller Description 
Create User Profile 

Modify User Profile 

Diagnose 

Terminate Machine Processing 
Initiate Process 

Modify Resource Management Controls 
Create Mode Description 

Create Class of Service Description 


Reserved (binary Q) 


Special authorizations 


(1 


= authorized) 


All object authority 
Load (unrestricted) 
Dump (unrestricted) 
Suspend object (unrestricted) 
Load (restricted) 
Dump (restricted) 
Suspend object (restricted) 
Process control 
Reserved (binary 0) 
Service authority 
Auditor authority 
Spool control 
Reserved (binary 0) 
Modify machine attributes 
- Group 2 
- Group 3 
- Group 4 
- Group 5 
- Group 6 
- Group 7 
- Group 8 
- Group 9 


Materialize User Profile (MATUP) 


Char(16) 
Char(4) 


Bit O 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bits 11-31 
Char(4) 


. Bit 0 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bit 11 
Bit 12-23 
Bits 24-31 
Bit 24 
Bit 25 
Bit 26 
Bit 27 
Bit 28 
Bit 29 
Bit 30 
Bit 31 
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Note: Group 1 requires no authorization. 


* Storage authorization Bin(4) 
The maximum amount of auxiliary storage (in units of 1024 bytes) that can be allocated for the J 
Storage of objects owned by this user profile 


« Storage utilization Bin(4) 
The current amount of auxiliary storage (in units of 1024 bytes) allocated for the storage of objects 
owned by this user profile 


e User profile status Char(2) 


— Verify storage utilization Bit 0 1=Storage utiliza- 
tion has not been verified and may not be correct. The Materialize Authorized Objects instruc- 
tion can be used to verify the storage utilization. 


— Reserved (binary 0) Bits 1-15 
e Reserved (binary 0) Char(1) 
e Object audit level Char(1) 
— Reserved (binary 0) Bits 0-5 
— Audit object changes for this user Bit 6 
— Audit object reads for this user Bit 7 
e User Audit level 1 Char(4) 
e User Audit level 2 : , Char(4) 
— Audit program adoption Bit 0 
(1 =audit) 
— Reserved (binary 0) Bits 1-31 -) 
e Reserved (binary 0) Char(4) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
the materialization. 


The attributes that the instruction can materialize are described in the Create User Profile instruction. 


Authorization Required: 
e Operational 


— Operand 2 


Lock Enforcement 
e Materialize . 


— Operand 2 


Exceptions 
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Exception 


06 


08 


0A 


1A 


1C 


20 


22 


24 


2E 


36 


38 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 

02 machine context 

04 system object damage state 

05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 

01 pointer does not exist 

02 pointer type invalid 

03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 
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Operands 
1 2 
X X 
X X 
X X 
X X 
X X 

X 
X X 
X X 

X 
xX X 
X X 
X X 
X X 
X X 

X 
X 


Other 


x KK OK 
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Test Authority (TESTAU) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] S) 
TESTAU Available System object Required 
10F7 authority tem- or object tem- authority tem- 
plate receiver plate plate 
TESTAUB Branch options Available System object Required Branch targets 
1CF7 authority tem- or object tem- authority tem- 
plate receiver plate plate 
TESTAUI Indicator Available System object Required Indicator targets 
18F7 options authority tem- or object tem- authority tem- 


plate receiver 


plate 


Operand ?: Character(2) variable scalar (fixed length) or null. 


Operand 2: System pointer or space pointer data object. 


Operand 3: Character(2) scalar (fixed length). 


Operand 4-5: 


plate 


¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 


number. 


e Indicator Form-Numeric variable scalar or character variable scalar. 


ILE access 
TESTAU ( 


C 


: aggregate; OR 
null operand; 
var system object_or_template : pointer; 
var required_authority : aggregate; 

) : signed binary /* return_code */ 


var receiver 


The return code will be set as follows: 


Return_Code Meaning 
1 Authorized. 
8 Not Authorized. 


Description: This instruction verifies that the object authorities and/or ownership rights specified by 
operand 3 are currently available to the process for the object specified by operand 2. 


If operand 1 is not null, all of the authorities and/or ownership specified by operand 3 that are currently 
available to the process are returned in operand 1. 


If an object template is not specified (i.e. operand 2 is a system pointer), then authority verification is 
performed relative to the invocation executing this instruction. If an object template is specified (i.e. 
operand 2 is a space pointer), then authority verification is performed relative to the invocation speci- 
fied in the template. Specifying an invocation causes the invocations subsequent to it to be bypassed 
in the authority verification process. This has the influence of excluding the program adopted user 
profiles for any of these excluded invocations from acting as a source of authority to the authority ver- 
ification process. 
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The required authorities and/or ownership are specified by the required authority template of operand 
3. This template includes a test option that indicates whether all of the specified authorities are 
required or whether any one or more of the specified authorities is sufficient. This option can be used, 
for example, to test for operational authority by coding a template value of hex OFO1 in operand 3. 
Using the any option does not affect what is returned in operand 1. If operand 1 is not null and the any 
option is specified, ail of the authorities specified by operand 3 that are available to the process are 
returned in operand 1. 


If the required authority is available, one of the following occurs: 


¢ Branch form indicated 


— Conditional transfer of control to the instruction indicated by the appropriate branch target 
operand. 


e Indicator form specified 
— The leftmost byte of each of the indicator operands is assigned the following values. 


Hex F1- If the result of the test matches the corresponding indicator option 
Hex FO- If the result of the test does not match the corresponding indicator option 


If no branch options are specified, instruction execution proceeds to the next instruction. If operand 1 
is null and neither the branch or indicator form is used, an invalid operand type exception is signaled. 


The format for the available authority template (operand 1) is as follows: (1 = authorized) 


¢« Authorization template Char(2) 

— Object control Bit 0 

— Object management Bit 1 

— Authorized pointer Bit 2 

— Space authority Bit 3 

— Retrieve Bit 4 

— Insert Bit 5 

— Delete Bit 6 

— Update Bit 7 

— Ownership (1 = yes) Bit 8 

— Excluded Bit 9 

— Authority List management Bit 10 
— Reserved (binary 0) Bits 11-15 


If operand 2 is a system pointer, it identifies the object for which authority is to be tested. If operand 2 
is a space pointer, it provides addressability to the object template. The format for the optional object 
template is as follows: 


« Object template Char(32) 
— Relative invocation Bin(2) 
— Reserved (binary 0) Char(14) 
— System object System pointer 


The relative invocation field in the object template identifies an invocation relative to the current invo- 
cation at which the authority verification is to be performed. The value of the relative invocation field 
must be less than or equal to zero. A value of zero identifies the current invocation, -1 identifies the 

prior invocation, -2, the invocation prior to that, and so on. A value larger than the number of invoca- 
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tions currently on the invocation stack or a positive value results in the signaling of the template value 

invalid (hex 3801) exception. The program adopted and propagated user profiles for the identified invo- 

cation and older invocations will be included in the authority verification process. Program adopted 

user profiles for invocations newer than the identified invocation will not be included in the authority 2) 
verification process. If the current invocation is specified, its program adopted user profile is included 

whether or not it is to be propagated. 


The system object field specifies a system pointer which identifies the object for which authority is to 
be tested. 


The format for the required authority template (operand 3) is as follows: (1 = authorized) 


e Authorization template Char(2) 
— Object control Bit O 
— Object management Bit 1 
— Authorized pointer Bit 2 
— Space authority Bit 3 
— Retrieve Bit 4 
— Insert Bit 5 
— Delete Bit 6 
— Update Bit 7 
— Ownership (1 = yes) ‘Bit 8 
— Excluded Bit 9 | 
— Authority List management Bit 10 2) 
— Reserved (binary Q) Bits 11-14 
— Test option Bit 15 


0 = All of the above authorities must be present. 
1 = Any one or more of the above authorities must be present. 


This instruction will tolerate a damaged object referenced by operand 2 when the reference is a 
resolved pointer. The instruction will not tolerate damaged contexts or programs when resolving 
pointers. Damaged user profiles encountered during the authority verification processing result in the 
signaling of the authority verification terminated due to damaged object exception. 
Resultant Conditions 

e Authorized - the required authority is available. 


« Unauthorized - the required authority is not available. 


Authorization Required: 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
« Materialize 


— Contexts referenced for address resolution J 


Exceptions 
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Operands 
Exception 1 2 3 Other 


06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


~ KK WK 
x KK RK 
~ K K K 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 
02 machine context damage state X 


04 system object damage state X X X X 


x 


05 authority verification terminated due to damaged object 


44 partial system object damage X X X X 


1A Lock state 
01 invalid lock state X 


1C Machine-dependent exception 


Q3 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X X 
02 object destroyed X X X 
Q7 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X X X 


02 pointer type invalid X X X 


2c Program execution 


04 invalid branch target X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 scalar type invalid X X X 


03 scalar value invalid Xx 


36 Space management 


01 space extension/truncation X 
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Operands 
Exception 1 2 3 Other 
38 Template specification 
01 template value invalid X 2 
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Test Extended Authorities (TESTEAU) 


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5] 
TESTEAU Available Required Relative invo- 
10FB authority tem- authority tem- cation 
plate receiver plate 
TESTEAUB Branch options Available Required Relative invo- Branch targets 
1CFB authority tem- authority tem- cation 
plate receiver plate 
TESTEAUI Indicator Available Required Relative invo- Indicator targets 
18FB options authority tem- authority tem- cation 
plate receiver plate 
Operand 1: Character(8) variable scalar (fixed length) or null 
Operand 2: Character(8) scalar (fixed length) 
Operand 3: Binary(2) variable scalar (fixed length) or constant, or null 
Operand 4-5: 
¢ Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction 
number. 


¢ /ndicator Form-Numeric variable scalar or character variable scalar. 


ILE access 


TESTEAU ( 
var receiver : aggregate; OR 
null operand; 
: aggregate; 
signed binary; OR 
null operand; 
) : signed binary /* return_code */ 


var required_authority 
var relative invocation : 


The return code will be set as follws: 


Return_Code Meaning 
1 Authorized. 
8 Not Authorized. 


Description: This instruction verifies that the privileged instructions and special authorities specified 
by operand 2 are currently available to the process. 


If operand 14 is not null, all of the privileged instructions and special authorities specified by operand 2 
that are currently available to the process are returned in operand 1. 


Note: The term authority verification refers to the testing of the required privileged instruction and 
special authorities. 


lf operand 3 is null, the authority verification is performed relative to the invocation executing this 
instruction. If an operand 3 is specified, the authority verification is performed relative to the invoca- 
tion specified. Specifying an invocation causes the invocations subsequent to it to be bypassed in the 
authority verification process. This has the influence of excluding the program adopted user profiles 
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for any of these excluded invocations from acting as a source of authority to the authority verification 


process. 


The required privileged instructions and special authorities are specified by the required authority tem- J 
plate of operand 2. 


If the required authority is available, one of the following occurs: 


¢ Branch form indicated 


— Conditional transfer of control to the instruction indicated by the appropriate branch target 
operand. 


¢ Indicator form specified 


— The leftmost byte of each of the indicator operands is assigned the following values. 


Hex F1- If the result of the test matches the corresponding indicator option 
Hex FO- If the result of the test does not match the corresponding indicator option 


If no branch options are specified, instruction execution proceeds to the next instruction. If operand 1 
is null and neither the branch or indicator form is used, an invalid operand type exception is signaled. 


The format for the available authority template (operand 1) is as follows: (1 = authorized) 


* Authority template 


— Privileged instruction template 


Create Logical Unit Description 
Create Network Description 

Create Controller Description 
Create User Profile 

Modify User Profile 

Diagnose 

Terminate Machine Processing 
Initiate Process 

Modify Resource Management Control 
Create Mode Description 

Create Class of Service Description 


Reserved (binary 0) 


— Special authority template 


All object 

Load (unrestricted) 
Dump (unrestricted) 
Suspend (unrestricted) 
Load (restricted) 
Dump (restricted) 
Suspend (restricted) 
Process control 


Reserved (binary 0) 


Char(8) 
Char(4) 
. Bit 0 
Bit 1 
Bit 2 ( 
Bit 3 2 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bits 11-31 
Char(4) 
Bit O 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 J 


Bit 8 
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- Service Bit 9 
- Auditor authority Bit 10 
- §Spool control Bit 11 
- Reserved (binary Q) Bit 12-23 
- Modify Machine Attributes Bit 24-31 
¢ Group 2 Bit 24 
e Group 3 Bit 25 
e Group 4 Bit 26 
e Group 5 Bit 27 
e Group 6 Bit 28 
e Group 7 Bit 29 
e Group 8 Bit 30 
« Group 9 Bit 31 


The format for the required authority template (operand 2) is as follows: (1 = authorized) 


e Required authority Char(8) 

— Privileged instruction template Char(4) 

- Create Logical Unit Description Bit O 

- Create Network Description Bit 1 

- Create Controller Description . Bit 2 

- Create User Profile Bit 3 

- Modify User Profile Bit 4 

- Diagnose Bit 5 

- Terminate Machine Processing Bit 6 

- Initiate Process Bit 7 

- Modify Resource Management Control Bit 8 

- Create Mode Description Bit 9 

- Create Class of Service Description Bit 10 

- Reserved (binary 0) Bits 11-31 
— Special authority template Char(4) 

- All object Bit 0 

- Load (unrestricted) Bit 1 

- Dump (unrestricted) Bit 2 

- Suspend (unrestricted) Bit 3 

- Load (restricted) Bit 4 

- Dump (restricted) Bit 5 

- Suspend (restricted) Bit 6 

- Process control Bit 7 

- Reserved (binary 0) Bit 8 

- Service Bit 9 

- Auditor authority Bit 10 
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- Spool control Bit 11 
- Reserved (binary 0) Bit 12-23 
- Modify Machine Attributes Bit 24-31 
¢ Group 2 Bit 24 
« Group 3 Bit 25 
« Group 4 Bit 26 
« Group 5 Bit 27 
« Group 6 Bit 28 
e Group 7 Bit 29 
e Group 8 Bit 30 
e Group 9 Bit 31 


The relative invocation operand (operand 3) identifies an invocation relative to the current invocation at 
which the authority verification is to be performed. The value of the relative invocation field must be 
less than or equal to zero. A value of zero identifies the current invocation, -1 identifies the prior invo- 
cation, -2, the invocation prior to that, and so on. A value larger than the number of invocations cur- 
rently on the invocation stack or a positive value results in the signaling of the scalar value invalid (hex 
3203) exception. 


An immediate value is not allowed for operand 3. 


The program adopted and propagated user profiles for the identified invocation and older invocations 
will be included in the authority verification process. Program adopted user profiles for invocations 
newer than the identified invocation will not be included in the authority verification process. Ifthe 
current invocation is specified, its program adopted user profile is included whether or not it is to be 
propagated. 


Damaged user profiles encountered during the authority verification processing result in the signaling 
of the authority verification terminated due to damaged object exception. 
Resultant Conditions 

e Authorized - the required authority is available. 


e Unauthorized - the required authority is not available. 


Authorization Required: 
e« Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X X 
02 boundary alignment X X X 
03 range X X X 
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Exception 


08 


0A 


10 


1A 


20 


22 


24 


2C 


2E 


32 


36 


38 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 

02 machine context damage state 

04 system object damage state 

05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


04 invalid branch target 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 


Test Extended Authorities (TESTEAU) 


Operands 
1 2 
X X 
X X 
X 
X 
X X 
X X 
X 
X X 
X X 
X X 
X X 
X X 
X 


~< Ww 


Other 


~ 
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Chapter 18. Process Management Instructions 
__ 
This chapter describes instructions used for process management. These instructions are in alpha- 7 


betic order. For an alphabetic summary of all the instructions, See Appendix A, “Instruction 
Summary.” 


Materialize Process Activation Groups (MATPRAGP) .............0.. 2.0.00 ee eens 18-3 
Materialize Process Attributes (MATPRATR) .........0.. 20.000 0 ee ee ee ee es 18-5 
Wait On Time (WAITTIME) . 2... ee 18-18 


© Copyright 1BM Corp. 1991, 1993 18-1 
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Materialize Process Activation Groups (MATPRAGP) 


Op Code (Hex) Operand 1 
0331 Receiver 


Operand 1: Space pointer 


ILE access 


MATPRAGP ( 
receiver : space pointer 
) 


Warning: The following information is subject to change from release to release. Use it with caution 
and be prepared to adjust for changes with each new release. 


Description: This instruction provides a list of the activation groups which exist in the current process. 
Operand 1 locates a template which receives information. 


The materialization template identified by operand 1 must be 16-byte aligned in the space. This 
materialization template has the following format: 


¢ Number of bytes provided for materialization Bin(4) 

¢ Number of bytes available for materialization | Bin(4) 

¢ Activation group count Bin(4) 

¢ Activation group list 2 
array(1..activation group count) of UBin(4) | 


The Materialize Activation Group Attributes instruction can be used to examine the attributes of an 
individual activation group. 


The first 4 bytes of the materialization template specify the number of bytes provided for use by the 
instruction. In all cases if the number of bytes provided is less than 8 then a materialization length 
(hex 3803) exception will be signaled. 


The second 4 bytes of the instruction indicate the actual number of bytes available to be returned. In 
no case does the instruction return more bytes of information than those available. 


activation group count 


This is the number of activation groups within the process. It is also the extent of 
the activation group list which follows. 


activation group list 
This is the list of activation groups which exist within the current process. 


This is an array of activation group mark values. Each entry denotes an activation 
group currently existent within the process. 


Authorization: n/a 
Lock Enforcement: n/a 


Exceptions 
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Exception 


06 


08 


10 


1C 


20 


38 


Addressing 

01 space addressing violation 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 


44 partial system object damage 


Machine-dependent exception 
03 machine storage limit exceeded 


04 object storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Template specification 


03 Materialization length 


Domain specification 


01 Domain Violation 


Materialize Process Activation Groups (MATPRAGP) 


Operands 

1 Other 

X 

X 

X 

X 

X 

X X 
X 
X 
X 
X 

X 

X 
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Materialize Process Attributes (MATPRATR) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0333 Receiver Process control Materialization 
space options 


Operand 1: Space pointer. 
Operand 2: System pointer or null. 


Operand 3: Character scalar(1). 


ILE access 


MATPRATR ( 
receiver : space pointer; 
var process control space : system pointer; OR 
null operand; 
var materialization_ options : aggregate 


) 


Description: The instruction causes either one specific attribute or all the attributes of the designated 
process to be materialized. 


Operand 1 specifies a space that is to receive the materialized attribute values. The space pointer 
specified in operand 1 must address a 16-byte aligned area. ( 


Operand 2 is a system pointer identifying the process control space associated with the process whose J 
attributes are to be materialized. If operand 2 is null, the process issuing the instruction is the subject 

process. If the subject process’s attributes are being materialized by another process, that process 

must be the original initiator of the subject process or the governing user profile(s) must have process 

control special authorization. 


Operand 3 is a character scalar(1) specifying which process attribute is to be materialized. A value of 
hex 00 results in all the attributes of a process being materialized in the format described in the Initiate 
Process instruction for the process definition template. Other options allow materialization of special- 
ized process attributes. 


A summary of the allowable hex values for operand 3 follows. 


00 Entire orginal PDT 
01-OB Entire Char(4) process control attributes field 


0c Signal event control mask 

OD Number of event monitors 

OE Priority 

OF Main storage pool id 

10 Maximum temporary auxiliary storage allowed ; 
11 Time slice interval 

12 Default time-out interval 

13 Maximum processor time allowed 

14 Multiprogramming level class ID 

15 Modification control indicators 

16 User profile pointer 

17 Process communication object (PCO) pointer 
18 Process name resolution list space pointer 
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19 

1A 
1B 
1C 
ig 
20 
21 

22 
23 

24 
29 
26 
27 
28 
29 


Materialize Process Attributes (MATPRATR) 


Initiation phase program pointer 

Termination phase program pointer 

Problem phase program pointer 

Process default exception handler (PDEH) program pointer 
Process access group pointer 

Process status indicators 

Process resource usage attributes 
Subordinate processes identification attributes 
Performance status attributes 

Execution status attributes 

Process control space system pointer 
Adopted user profile list space pointer 

Entire Char(4) process contro/ attributes field 
Process category 

Queue space system pointer 


Note that there exist differences in the operand 3 value definitions between this instruction and the 
Modify Process Attributes instruction. 


The materialization template has the following general format when a process scalar attribute is mate- 


rialized: 


e Materialization size specification 


Number of bytes provided for materialization 


Number of bytes available for materialization 


¢ Process scalar attributes 


Char(8) 
Bin(4) 


* Bin(4) 


Char(*) 


The materialization template has the following general format when a process pointer attribute is 
materialized: 


e Materialization size specification 


e Res 


Number of bytes provided for materialization 
Number of bytes available for materialization 


erved (binary 0) 


e Process pointer attribute 


Char(8) 
Bin(4) 
Bin(4) 
Char(8) 


System pointer 
or 
Space pointer 


Note: The values of the entry associated with an asterisk (*) are ignored by this instruction. 


The following attributes require materialization targets of varying lengths. The attributes to be materi- 


alized a 


nd their operand 3 materialization option values follow. 


e Process control attributes 


Values hex 01 through hex OB or hex 27 cause the 4-byte process control attributes value to be 
placed in the byte area identified by operand 1. The individual attributes and the corresponding 
values are as follows: 


Process type 


O = Dependent process 
1 = Independent process 


Instruction wait access state control 


0 = Access state modification is not allowed 
41 = Access state modification is allowed if specified 


Char(4) 


Bit O 


Bit 1 
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Time slice end access state control Bit 2 


0 = Access state modification is not allowed 
1 = Access state modification is allowed if specified 


Time slice end event option Bit 3 


0 = Time slice expired without entering instruction wait event is not signaled 
1 = Time slice expired without entering instruction wait event is signaled 


Reserved (binary 0) Bit 4 
Initiation phase program option Bit 5 


0 = No initiation phase program specified (do not enter initiation phase) 
1 = Initiation phase program specified (enter initiation phase) 


Problem phase program option Bit 6 


0 
1 


Termination phase program option Bit 7 


0 No termination phase program specified (do not enter termination phase) 
1 = Termination phase program specified (enter termination phase) 


No problem phase program specified (do not enter problem phase) 
Problem phase program specified (enter problem phase) 


Process default exception handler option Bit 8 


0 = No process default exception handler 
1 = Process default exception handler specified 


Process NRL (name resolution list) option Bit 9 
0 = No process NRL specified 

1 = Process NRL specified 

Process access group option Bit 10 


0 = No process access group specified 
1 = Process access group specified 


Process adopted user profile list option Bit 11 
0 = No process adopted user profile list specified 

1 = Process adopted user profile list specified 

Process category specified Bit 12 


O = No process category specified when the process was initiated 
1 = A process category was specified when the process was initiated 


Recycling control for process Bit 13 
storage addresses used by user state programs 


OQ = Process storage addresses used by user state programs are not recycled within the 


process 


1 = Process storage addresses used by user state programs are recycied within the process 


Implicitly created activation group’s Bit 14 
automatic storage access group membership control 


O = The machine is free to create automatic storage areas of implicitly created activation 


groups within the process access group 


Note: This in no way guarantees that the automatic areas will in fact be access group 
members. This is an advisory flag informing the machine that the MI user would prefer 


these areas to be access group members. 
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| 1 = Implicitly created activation group’s automatic storage areas will not be created within the 
| process access group 


Cc | — Implicitly created activation group’s Bit 15 
static storage access group membership control 


| 0 = The machine is free to create static storage areas of implicitly created activation groups 
| within the process access group 


Note: This in no way guarantees that the static areas will in fact be access group 
members. This is an advisory flag informing the machine that the MI user would prefer 
these areas to be access group members. 

1 = Implicitly created activation group’s static storage areas will not be created within the 
process access group 


— Implicitly created activation group’s Bit 16 
default heap storage access group membership control 


groups within the process access group 


Note: This in no way guarantees that the activation group default heap areas will in fact be 
access group members. This is an advisory flag informing the machine that the MI user 
would prefer these areas to be access group members. 

1 = Implicitly created activation group’s default heap storage areas will not be created within 
the process access group 


| 
| 
| 
| 
| 
| 
| 
| OQ = The machine is free to create default heap storage areas of implicitly created activation 
| 
| 
| 
| 
| 
| 
| — Reserved (binary 0) Bits 17-31 
¢« Signal event control mask 

The materialization of the control mask is as follows: 

. — Hex 0C = Signal event control mask Char(2) 
e Number of event monitors 
The materialization of this attribute is as follows: 
— Hex 0D = Number of event monitors Bin(2) 


The resource management attributes and data types are as follows: 


e Hex OE = Process priority Char(1) 
e Hex OF = Process storage pool ID Char(1) 
e Hex 10 = Maximum temporary auxiliary storage allowed Bin(4) 

e Hex 11 = Time slice interval Char(8) 
e Hex 12 = Default time-out interval Char(8) 
e Hex 13 = Maximum processor time allowed Char(8) 
e Hex 14 = Process multiprogramming level class ID Char(1) 
e Hex 15 = Modification control indicators Char(8) 


The modification control indicators are materialized when the operand 3 value is hex 15. Each indi- 
cator specifies the modification options allowed to a process upon itself by the initiating process. The 
possible values of each modification control indicator are as follows: 


00 
01 


c , 


Modification of the attribute is not allowed. 


Modification is allowed in the initiation or termination phases only. 


Modification is allowed in all phases (initiation, problem, and termination). 


| 
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¢ Instruction wait access state control Bits 0-1 

e Time slice end access state control Bits 2-3 

« Time slice event option Bits 4-5 

e Reserved (binary 0) Bits 6-7 

e Problem phase program option Bits 8-9 

e Termination phase program option Bits 10-11 
e Process default exception handler option Bits 12-13 
e Process NRL option Bits 14-15 
e Signal event control mask Bits 16-17 
e Process priority Bits 18-19 
e Process storage pool identification Bits 20-21 
e Maximum temporary auxiliary storage allowed Bits 22-23 
e Time slice interval Bits 24-25 
¢ Default time-out interval Bits 26-27 
e Maximum processor time allowed Bits 28-29 
e Process MPL class ID Bits 30-31 
e User profile pointer Bits 32-33 
e Reserved Bits 34-35 
e Process NRL pointer Bits 36-37 
e Termination phase program pointer Bits 38-39 
e Problem phase program pointer Bits 40-41 
e Process default exception handler Bits 42-43 
e Process adopted user profile list Bits 44-45 
e Process adopted user profile list option Bits 46-47 
e Process category Bits 48-49 
e Recycling control for process Bits 50-51 

storage addresses used by user state programs 
« Reserved (binary 0) Bits 52-63 


Materialize Process Attributes (MATPRATR) 


The process pointer attributes which may be materialized are the following: 
e Hex 16 = Process user profile pointer 


The system pointer with addressability to the user profile is placed into the space addressed by 
operand 1. If the materialization option (hex 00) is specified in operand 3, a reserved Char(9) field 
is included at this point. This user profile is the process user profile assigned by the Initiate 
Process or Modify Process Attribute instruction. 


e Hex 17 = Process communication object (PCO) pointer 
The PCO pointer is placed in the space addressed by operand 1. 


e Hex 18 = Process name resolution list 


The space pointer to the NRL is placed in the space addressed by operand 1. 
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Hex 19 = Initiation phase program pointer 


The system pointer to the program is placed in the space addressed by operand 1. 


Hex 1A = Termination phase program pointer 


The system pointer to the program is placed in the space addressed by operand 1. 


Hex 1B = Problem phase program pointer 


The system pointer to the program is placed in the space addressed by operand 1. 


Hex 1C = PDEH (process default exception handler program) 


The system pointer to the program is placed in the space addressed by operand 1. 


Hex 1F = Process access group 


The system pointer with addressability to the PAG is placed in the space addressed by operand 1. 


Hex 20 = Process status indicators 


Process status indicators are materialized when the value of operand 3 is hex 20. The format and 


associated values of this attribute are as follows: 
— Process states 
- External existence state 


000 = Suspended 

010 = Suspended, in instruction wait 
100 = Active, in ineligible wait 

101 = Active, in current MPL 

110 = Active, in instruction wait 


- Invocation exit active 
- Reserved (binary 0) 
- Internal processing phase 


001 = Initiation phase 
010 = Problem phase 
100 = Termination phase 


- Reserved (binary 0) 


— Process interrupt status (1 = pending) 
- Time slice end pending 
- Transfer lock pending 
- Asynchronous lock retry pending 
- Suspend process pending 
- Resume process pending 
- Resource management attribute modify pending 
- Process attribute modify pending 
- Terminate machine processing pending 
- Terminate process pending 
- Wait time-out pending 
- Event schedule pending 
- Machine service pending 


- Cancel Long Running MI Instruction 


Char(2) 
Bits 0-2 


Bit 3 
Bits 4-7 
Bits 8-10 


Bits 11-15 
Char(2) 
Bit O 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bit 11 
Bit 11 
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- Reserved (binary 0) Bits 13-15 
— Process initial internal termination status Char(3) 
- Initial internal termination reason Bits 0-7 J 


Hex 80 = Return from first invocation in problem phase. 

Hex 40 = Return from first invocation in initiation phase, and no problem phase program 
specified. 

Hex 20 = Terminate Process instruction issued by this process to itself. 

Hex 10 = Exception was not handled by the process. 

Hex 00 = Process terminated externally. 


- Initial internal termination code Bits 8-23 
The code is assigned in one of the following ways: 


1. If the termination is caused by a Return External instruction from the first invocation, 
then this code is binary 0’s. 


2. The code is assigned by operand 2 of the Terminate Process instruction. This code is 
also given to subordinate processes involved in the termination. 


3. The code is assigned by the original exception code that caused process termination to 
commence. This code is also given to subordinate processes involved in the termi- 


nation. 
— Process initial external termination status Char(3) 
- Initial external termination reason: ,Bits 0-7 


Hex 80 = Terminate Process instruction issued explicitly to this process from another 


process. o « 
Hex 40 = A superordinate process has been terminated. 2) 
Hex 00 = Process terminated internally. 
- Initial external termination code: Bits 8-23 


This code is supplied by the termination code in operand 2 of the Terminate Process 


instruction. 
— Process final termination status Char(3) 
- Final termination reason: Bits 0-7 


Hex 80 = Return instruction from first invocation. 

Hex 40 = Terminate Process instruction issued by the process being materialized. 

Hex 20 = Terminate Process instruction issued to the process being materialized by 
another process. 

Hex 10 = Exception not handled by this process. 

Hex 08 = Terminate Process instruction issued to superordinate of the process being 
materialized. 

Hex 04 = Superordinate process of the process being materialized completed termination 
phase. 


- Final termination code is assigned in one of Bits 8-23 
the following ways: 


1. If the termination is caused by a Return External instruction from first invocation, then 
this code is binary 0’s. 


2. The termination code is assigned by the Terminate Process instruction. 


3. The termination code is assigned by the original exception code that caused process 3 
termination. 
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The process final termination status is presented as event-related data in the terminate 
process event. Usually the event is the only source of the process final termination 
status since the process will cease to exist before its attributes can be materialized. 


Hex 21 = Process resource usage attributes 


Process resource uSage attributes are materialized when the value of operand 3 is hex 21. The 
format and associated values of this attribute are as follows: 


— Total temporary auxiliary storage used Bin(4) 
— Total processor time used Char(8) 
— Number of locks currently held by the process Bin(2) 


(including implicit locks) 


Hex 22 Subordinate processes identification attributes Subordinate processes identification attri- 
butes are materialized when the value of operand 3 is hex 22. The format and associated values of 
this attribute are as follows: 


— Materialization size specification Char(8) 
- Number of bytes provided for matialization Bin(4) 
- Number of bytes available for materialization Bin(4) 
— Number of immediately subordinate processes Bin(2) 
— Reserved (binary 0) Char(6) 
— System pointer to the process control space _System pointer(s) for 


each subordinate process (repeated for each immediately subordinate process) 


Hex 23 = Process performance attributes Process performance attributes are materialized when 
the value of operand 3 is hex 23. The format and associated values of this attribute are as follows: 


— Materialization size specification Char(8) 
- Number of bytes provided for Bin(4) 
materialization 
- Number of bytes available for Bin(4) 
materialization 
— Number of synchronous page reads into Bin(4) 
main storage associated with data base 
— Number of synchronous page reads into Bin(4) 
main storage not associated with data base 
— Total number of synchronous page writes from Bin(4) 
main storage. This includes writes associated with and not associated with data base. 
— Number of transitions into ineligible wait UBin(2) 
state 
— Number of transitions into an instruction wait UBin(2) 
— Number of transitions into ineligible UBin(2) 
wait state from an instruction wait 
— Timestamp of materialization Char(8) 
— Number of asynchronous reads into main Bin(4) 


storage associated with data base 


— Number of asynchronous reads into main Bin(4) 
storage not associated with data base 


— Number of synchronous writes from main Bin(4) 
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storage associated with data base 


— Number of synchronous writes from main Bin(4) 
storage not associated with data base 


— Number of asynchronous writes from main Bin(4) 
storage associated with data base 


— Number of asynchronous writes from main Bin(4) 
storage not associated with data base 


— Total number of writes from main Bin(4) 
storage of permanent objects 


— Total reads and writes performed Bin(4) 
for checksum updating due to writes of checksum protected objects 


— Number of page faults on process Bin(4) 
access group objects 


— Number of internal effective address Bin(4) 
overflow exceptions 


— Number of internal binary Bin(4) 
overflow exceptions 


— Number of internal decimal Bin(4) 
overflow exceptions 


— Number of internal floating point .Bin(4) 
overflow exceptions 


— Number of times a page fault occurred Bin(4) 
on an address that was currently part of an auxiliary storage I/O operation 


— Number of times the process Bin(4) 
explicitly waited for outstanding asynchronous |/O operations to complete 


Each of the Bin(2) counters has a limit of 32 767. If this limit is exceeded, the count is set to 0, and 
no exception is signaled. 


The process performance attributes are not supplied with materialization option hex 00. 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the 
instruction. This value is supplied as input to the instruction and is not modified by the instruction. 
A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the 
information requested, then the excess bytes are unchanged. No exceptions (other than the 
materialization length (hex 3803) exception described previously) are signaled in the event that the 
receiver contains insufficient area for the materialization. 


Hex 24 = Process execution status attributes 


Process execution status attributes are materialized when the value of operand 3 is hex 24. The 
format and associated values of this attribute are as follows: 


— Process priority Char(2) 
- Machine interface priority Char(1) 
- Machine adjusted priority Char(1) 


Normal value is hex 80. This value is dynamically modified by the machine. 


— Pending interruptions Char(2) 
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- Time slice end Bit O 

- Transfer lock Bit 1 

- Asynchronous !ock retry Bit 2 

- Suspend process Bit 3 

- Resume process Bit 4 

- Modify resource management attribute Bit 5 

- Modify process attribute Bit 6 

- Terminate machine processing Bit 7 

- Terminate process Bit 8 

- Wait time-out Bit 9 

- Event Bit 10 

- Machine service pending Bit 11 

- Cancel Long Running MI Instruction Bit 11 

- Reserved (binary 0) Bits 13-15 
— Execution status Char(2) 

- Suspended Bit O 

- Instruction wait Bit 1 

- In MPL ‘Bit 2 

- Ineligible wait Bit 3 

- Reserved (binary 0) Bits 4-15 
— Wait status Char(2) 

- Wait on event Bit 0 

- Dequeue Bit 1 

- Lock Bit 2 

- Wait on time Bit 3 

- Wait to start a commit cycle Bit 4 

- Reserved (binary 0) Bits 5-15 
— Process class identification Char(2) 

- Storage pool class Char(‘) 

- MPL class Char(1) 
— Processor time used Char(8) 
— Performance attributes Char(78) 

- Number of synchronous reads into main Bin(4) 

storage associated with data base 
- Number of synchronous reads into main Bin(4) 
storage not associated with data base 
- Total number of synchronous page writes from Bin(4) 


main storage. This includes writes associated with and not associated with data base. 


Transitions to ineligible wait 


UBin(2) 


Chapter 18. Process Management Instructions 


18-14 


Materialize Process Attributes (MATPRATR) 


- Transitions to instruction wait 
- Transitions to ineligible from instruction wait 


- Number of asynchronous reads into main 
storage associated with data base 


- Number of asynchronous reads into main 
storage not associated with data base 


- Number of synchronous writes from main 
storage associated with data base 


- Number of synchronous writes from main 
storage not associated with data base 


- Number of asynchronous writes from main 
storage associated with data base 


- Number of asynchronous writes from main 
storage not associated with data base 


- Total number of writes from main 
storage of permanent objects 


- Total reads and writes performed 


UBin(2) 
UBin(2) 


Bin(4) J 


Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 


Bin(4) 


for checksum updating due to writes of checksum protected objects 


- Number of page faults on process 
access group objects 


- Number of internal effective address 
overflow exceptions 


- Number of internal binary 
overflow exceptions 


- Number of internal decimal 
overflow exceptions 


- Number of internal floating point 
overflow exceptions 


- Number of times a page fault occurred 


Bin(4) 
Bin(4) 
Bin(4) J 
Bin(4) 
Bin(4) 


Bin(4) 


on an address that was currently part of an auxiliary storage I/O operation 


- Number of times the process 


Bin(4) 


explicitly waited for outstanding asynchronous |/O operations to complete 


e Hex 25 = Process control space pointer 


A system pointer to the process control space is materialized when the value of operand 3 is hex 
25. If a process control space pointer is supplied in operand 2, it is ignored. A pointer to the 
process that is executing the MATPRATR instruction is always materialized. 


« Hex 26 = Adopted user profile list attributes 


A materialization option’s value of hex 26 causes the adopted user profile list attributes to be mate- 


rialized as follows: 
— Materialization size specification 
- Number of bytes provided for materialization 
- Number of bytes available for materialization 
— Reserved (binary 0) 


— Pointer to the adopted user profile list 


Char(8) 
Bin(4) 
Bin(4) 


Char(8) J 


Space pointer 
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last used to set this attribute 


— Number of user profiles in the Bin(2) 
encapsulated adopted user profile list 

— Reserved Char(14) 

— List of user profiles in the System pointers 


encapsulated adopted user profile list (one system pointer to each user profile in the list) 


Due to verifications performed on the user profiles specified in an adopted process user profile list 
input to either the Initiate Process or Modify Process instructions, the encapsulated adopted user 
profile list may differ from the input list. When verification of an input user profile fails, it is not 
included in the encapsulated list. 


The adopted user profile list attributes are not supplied with materialization option hex 00. 
e Hex 27 = Process control attributes 


A materialization option’s value of hex 27 causes the process control attributes to be materialized. 
Refer to the description of this materialization provided in prior text for this instruction. 


e Hex 28 = Process category Char(2) 

° Hex 29 = Queue Space system pointer 
The system pointer with addressability to the Queue Space is placed in the space addressed by 
operand 1. 


Authorization Required - 
e Process control special authorization 
— For materializing a process other than the one executing this instruction 
° Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 3 4 Other 
06 Addressing 

01 space addressing violation X X X 

02 boundary alignment X X X 

03 range Xx Xx Xx 

06 optimized addressability invalid Xx Xx X 
08 Argument/parameter 

01 parameter reference violation Xx xX Xx 
0A Authorization 

01 unauthorized for operation X 

04 unauthorized for process control X 
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Operands 
Exception 1 2 3 4 Other 


10 Damage encountered ; 
04 system object damage state X X X X X - 
05 authority verification terminated due to damaged object X 


44 partial system object damage X X X X X 


iA Lock state 


01 invalid lock state Xx 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X X 
02 object destroyed 
03 object suspended X X X 


07 authority verification terminated due to destroyed object X 


~*~ 
>< 
*< 


08 object compressed ~ X 


24 Pointer specification 
01 pointer does not exist X X X ; 


~< 
*< 


02 pointer type invalid X 


03 pointer addressing invalid object X 


28 Process state 


02 process control space not associated with a process X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 


03 scalar value invalid X 


36 Space management 


01 space extension/truncation X 


38 Template specification 


03 materialization length exception X 


Chapter 18. Process Management Instructions 18-17 


Wait On Time (WAITTIME) 


Wait On Time (WAITTIME) 


Op Code (Hex) Operand 1 
0349 Wait template 


Operand 1: Character(16) scalar (fixed-length) 


ILE access 


WAITTIME ( 
var wait_template : aggregate 


) 


Description: This instruction causes the process to wait for a specified time interval. The current 
process is placed in wait state for the amount of time specified by the wait template in accordance with 
the specified wait options. 


The format of the wait template for operand 1 is: 


e Wait time interval Char(8) 
¢ Wait options Char(2) 


— Access state control for entering wait Bit O 


0 = Do not modify access state 
1 = Modify access state 


— Access state control for leaving wait Bit 1 


0 = Do not modify access state 
1 = Modify access state 


— MPL (multiprogramming level) Bit 2 
control during wait 
0 = Do not remain in current MPL set 
4 = Remain in current MPL set 
— Reserved Bits 3-15 
e Reserved Char(6) 


The format of the wait time interval value is that of a 64-bit unsigned binary value where bit 41 is equal 
to 1024 microseconds, assuming the bits are numbered from 0 to 63. 


The access state control options control whether the process access group (PAG) will be explicitly 
transferred between main and auxiliary storage when entering and leaving a wait as a result of exe- 
cution of this instruction. Specification of modify access state requests that the PAG be purged from 
main to auxiliary storage for entering a wait and requests that the PAG be transferred from auxiliary to 
main storage for leaving a wait. Specification of do not modify access state requests that the PAG not 
be explicitly transferred between main and auxiliary storage as a result of executing this instruction. 


The access state of the PAG is modified when entering the wait if the process’ instruction wait initi- 
ation access state control attribute specifies allow access state modification, if the access state control 
for entering wait option specifies modify access state, and if the MPL control during wait option speci- 
fies do not remain in current MPL set. 
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The MPL control during wait option controls whether the process will be removed from the current 
MPL (multiprogramming level) set or remain in the current MPL set when the process enters a wait as 
a result of executing this instruction. J 


When the MPL control during wait option specifies remain in current MPL set and the access state 
control for entering wait option specifies do not modify access state, the process will remain in the 
current MPL set for a maximum of 2 seconds. After 2 seconds, the process will automatically be 
removed from the current MPL set. The automatic removal does not change or affect the total wait 
time specified for the process in the wait time interval. 


Exceptions 
Operands 
Exception 1 2 3 4 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KK XK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X 


10 Damage encountered 


04 system object damage state X 


x< 


05 authority verification terminated due to damaged object 


44 partial system object damage X wt 


20 Machine support 
02 machine check Xx 
03 function check D4 


22 Object access 
02 object destroyed X 
03 object suspended X 
07 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X 


02 pointer type invalid X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
01 scalar type invalid xX 


x 


02 scalar attributes invalid 


03 scalar value invalid X . 


36 Space management 


01 space extension/truncation X 
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Chapter 19. Resource Management Instructions 


This chapter describes the storage and resource management instructions. These instructions are in 
alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
summary.” 
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Ensure Object (ENSOBJ) 


Op Code (Hex) Operand 1 
0381 System pointer 


Operand 1: System pointer. 


ILE access 


ENSOBU ( 
var system_pointer : system pointer 


) 


Description: The object identified by operand 1 is protected from volatile storage loss. The machine 
ensures that any changes made to the specified object are recorded on nonvolatile storage media. 
The access state of the object is not changed by this instruction. If operand 1 addresses a temporary 
object, no operation is performed because temporary objects are not preserved during a machine 
failure. No exception is signaled if temporary objects are referenced. 


Authorization Required 
¢« Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 


Exceptions 


Exception 1 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


~ KK KK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation xX 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 
04 system object damage state X 
05 authority verification terminated due to damaged object X 


44 partial system object damage X X 


1A Lock state 
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1¢C 


20 


22 


24 


2E 


30 


32 


36 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

04 object not eligible for operation 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Journal management 


02 entry not journaled 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Ensure Object (ENSOBJ) 


Operands 
1 Other 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
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Materialize Access Group Attributes (MATAGAT) 


Op Code (Hex) Operand 1 Operand 2 
03A2 Receiver Access group 


Operand 1: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATAGAT 
receiver : Space pointer; 
var access group : system pointer 


Description: The attributes of the access group and the identification of objects currently contained in 
the access group are materialized into the receiving object specified by operand 1. 


Objects requested to be in the access group may: 


e exist entirely in the access group, 


e exist partially in the access group and partially outside the access group, 


e or exist entirely outside the access group. 


The machine may also use the access group for enabling programs to run within a process. In this 
case, the Process Control Space (PCS) object is considered to exist partially in the access group, even 
if the access group membership was not requested when the PCS was created. 


Only objects which exist wholly or partially in the access group will be materialized. 


The materialization must be aligned on a 16-byte boundary. The format is: 


e Materialization size specification 
— Number of bytes provided for materialization 
— Number of bytes available for materialization 
e Object identification 
— Qbject type 
— Object subtype 
— Object name 
e Object creation options 


— Existence attributes 


0 = Temporary 

1 = Reserved 
— Space attribute 

O = Fixed-length 

1 = Variable-length 
— Context 


O = Addressability not in context 
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1 = Addressability in context 


Materialize Access Group Attributes (MATAGAT) 


— Reserved (binary 0) Bits 3-12 

— Initialize space Bit 13 2 
— Reserved (binary 0) Bits 14-31 

Reserved (binary 0) Char(4) 

Size of space Bin(4) 

Initial value of space Char(1) 

Performance class Char(4) 

— Space alignment Bit 0 


OQ = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space. If no space is specified for the object, this value must 
be specified for the performance class. 

1 = The space associated with the object is allocated to allow proper alignment of pointers at 
16-byte alignments within the space as well as to allow proper alignment of input/output 
buffers at 512-byte alignments within the space. 


— Reserved (binary 0) Bits 1-4 
— Default main storage pool Bit 5 
OQ = Process main storage pool is used for this object. 
1 = Machine default main storage pool is used for this object. 
— Reserved (binary 0) Bit 6 
— Block transfer on implicit access state Bit 7 { 


modification J 


0 = Minimum storage transfer size for this object is transferred. This value is 1 storage unit. 
1 Machine default storage transfer size is transferred. This value is 8 storage units. 


— Reserved (binary 0) Bits 8-31 
e Reserved (binary 0) Char(7) 
e Context System pointer 
e« Reserved (binary 0) Char(16) 
¢ Access group size UBin(4) 
¢ Available space in the access group UBin(4) 
« Number of objects in the access group UBin(4) 
e Reserved (binary 0) Char(4) 
e Access group object system pointer System pointer 


(repeated for each object currently contained 
in the access group) 


The receiver space contains the access group’s attributes (as defined by the Create Access Group 
instruction), the current status of the access group, and a system pointer to each object assigned to 
the access group. 


The access group size represents the total amount of space that has been allocated to the access 
group. 


The amount of available space represents the amount of space that is available in the access group for 2 
additional objects. 
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The number of objects in the access group is a count of the number of objects that are currently con- 
tained in the access group. This value is also the number of times that the access group object system 
pointer below is repeated. 


There is One access group object system pointer for each object currently assigned to the access 
group. The authorization field within each system pointer is not set. 


Authorization Required 
e« Retrieve 
— Operand 2 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 


Exception 1 2 Other 

06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK OK 
x KK RK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 


04 system object damage state X X X 


< 


05 authority verification terminated due to damaged object 


44 partial system object damage X X X 


1A Lock state 
01 invalid lock state Xx xX 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X 
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Exception 


24 


2E 


36 


38 


02 object destroyed 
03 object suspended 
07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Operands 
1 2 Other 
X X 
X X 
X 
X 
X X 
Xx Xx 
X 
X 
X 
X 
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Materialize Resource Management Data (MATRMD) 


Op Code (Hex) Operand 1 Operand 2 
0352 Receiver Control data 


Operand 1: Space pointer. 


Operand 2: Character(8) scalar 


ILE access 


MATRMD ( 
receiver : space pointer; 
var control data : aggregate 


Description: The data items requested by operand 2 are materialized into the receiving object speci- 
fied by operand 1. Operand 2 is an 8-byte character scalar. The first byte identifies the generic type of 
information being materialized, and the remaining 7 bytes further qualify the information desired. 


Operand 1 contains the materialization and has the following format: 


e Materialization size specification Char(8) 
— Number of bytes provided for materialization ~ Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Time of day Char(8) 

¢« Resource management data Char(*) 


The remainder of the materialization depends on operand 2 and on the machine implementation. The 
following values are allowed for operand 2: 


¢ Selection option Char(1) 
Hex 01 


Materialize processor utilization data 


Hex 03 = Materialize storage management counters 
Hex 04 = Materialize storage transient pool information 
Hex 08 = Materialize machine address threshold data 
Hex 09 = Materialize main storage pool information 
Hex 0A Materialize MPL control information 


Hex OC = Materialize machine reserved storage pool information 
Hex 11 = Materialize user storage area 1 

Hex 12 = Materialize auxiliary storage information 

Hex 13 = Materialize multiprocessor utilizations 

Hex 14 = Materialize Storage pool tuning 


e Reserved (binary 0) Char(7) 
The following defines the formats and values associated with each of the above materializations of 
resource management data. 
Processor Utilization (Hex 01): 

e Processor time since IPL (initial program load) Char(8) 


Processor time since IPL is the total amount of processor time used, both by instruction processes and 
internal machine functions, since IPL. The significance of bits within the field is the same as that 
defined for the time-of-day clock. 
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On a machine with more than one active processor, the value returned will be the average of the 
processor time used since IPL by all active processors. 


Storage Management Counters (Hex 03): 


e Access pending Bin(2) 
e Storage pool delays Bin(2) 
e Directory look-up operations Bin(4) 
e Directory page faults Bin(4) 
e Access group member page faults Bin(4) 
e Microcode page faults Bin(4) 
e Microtask read operations Bin(4) 
e Microtask write operations Bin(4) 
e Reserved Bin(4) 


Access pending is a count of the number of times that a paging request must wait for the completion of 
a different request for the same page. 


Storage pool delays is a count of the number of times that processes have been momentarily delayed 
by the unavailability of a main storage frame in the proper pool. 


Directory look-up operations is a count of the number of times that auxiliary storage directories were 
interrogated, exclusive of storage allocation or deallocation. 


Directory page faults is a count of the number of times that a page of the auxiliary storage directory , 
was transferred to main storage, to perform either a look-up or an allocation operation. J? 


Access group member page faults is a count of the number of times that a page of an object contained 
in an access group was transferred to main storage independently of the containing access group. 
This occurs when the containing access group has been purged or because portions of the containing 
access group have been displaced from main storage. 


Microcode page faults is a count of the number of times a page of microcode was transferred to main 
storage. 


Microtask read operations is a count of the number of transfers of one or more pages of data from 
auxiliary main storage on behalf of a microtask rather than a process. 


Microtask write operations is a count of the number of transfers of one or more pages of data from 
main storage to auxiliary storage on behalf of a microtask, rather than a process. 
Storage Transient Pool Information (Hex 04): 

e Storage pool to be used for the transient pool Bin(2) 
The pool number materialized is the number of the main storage pool, which is being used as the 
transient storage pool. A value of 0 indicates that the transient pool attribute is being ignored. 


Machine Address Threshold Data (Hex 08): 


e Total permanent addresses possible Char(8) 

e Total temporary addresses possible Char(8) 

e Permanent addresses remaining Char(8) a 
e Temporary addresses remaining Char(8) 
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e Permanent addresses threshold Char(8) 
e Temporary addresses threshold Char(8) 
Total permanent addresses possible is the maximum number of permanent addresses that can exist on 


the machine. 


Total temporary addresses possible is the maximum number of temporary addresses that can exist on 
the machine. 


Permanent addresses remaining is the number of permanent addresses that can still be created before 
address regeneration must be run. 


Temporary addresses remaining is the number of temporary addresses that can still be created before 
address regeneration must be run. 


Permanent addresses threshold is a number that, when it exceeds the number of permanent addresses 
remaining, causes the machine address threshold exceeded (hex 000C,05,01) event to be signaled. 
When the event is signaled, the threshold is reset to 0. 


Temporary addresses threshold is a number that, when it exceeds the number of temporary addresses 
remaining, causes the machine address threshold exceeded (hex 000C,05,01) event to be signaled. 
When the event is signaled, the threshold is reset to 0. 


Main Storage Pool Information (Hex 09): 


e Machine minimum transfer size . Bin(2) 
¢ Maximum number of pools Bin(2) 
e Current number of pools Bin(2) 
¢ Main storage size Bin(4) 
e Reserved (binary 0) Char(2) 
¢ Pool 1 minimum size Bin(4) 
¢ Individual main storage pool information Char(32) 
(repeated once for each pool, up to the current number of pools) 
— Pool size Bin(4) 
— Pool maintenance Bin(4) 
— Process interruptions (data base) Bin(4) 
— Process interruptions (nondata base) Bin(4) 
— Data transferred to pool (data base) Bin(4) 
— Data transferred to pool (nondata base) Bin(4) 
— Amount of pool not assigned to Bin(4) 
virtual addresses 
— Reserved (binary 0) Char(4) 


Machine minimum transfer size is the smallest number of bytes that may be transferred as a block to 
or from main storage. 


Maximum number of pools is the maximum number of storage pools into which main storage may be 
partitioned. These pools will be assigned the logical identification beginning with 1 and continuing to 
the maximum number of pools. 
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Current number of pools is a user-specified value for the number of storage pools the user wishes to 
utilize. These are assumed to be numbered from ‘1 to the number specified. This number is fixed by 
the machine to be equal to the maximum number of pools. 


Main storage size is the amount of main storage, in units equal to the machine minimum transfer size, 
which may be apportioned among main storage pools. 


Pool 1 minimum size is the amount of main storage, in units equal to the machine minimum transfer 
size, which must remain in pool 1. This amount is machine and configuration dependent. 


Individual main storage pool information is data in an array that is associated with a main storage pool 
by virtue of its ordinal position within the array. In the descriptions below, data base refers to all other 
data, including internal machine fields. Pool size, pool maintenance, amount of pool not assigned to 
virtual addresses and data transferred information is expressed in units equal to the machine minimum 
transfer size described above. 


Pool size is the amount of main storage assigned to the pool. 


Pool maintenance is the amount of data written from a pool to secondary storage by the machine to 
satisfy demand for resources from the pool. It does not represent total transfers from the pool to sec- 
ondary storage, but rather is an indication of machine overhead required to provide primary storage 
within a pool to requesting processes. 


Process interruptions (data base and nondata base) is the total number of interruptions to processes 
(not necessarily assigned to this pool) which were required to transfer data into the pool to permit 
instruction execution. 


Data transferred to pool (data base and nondata base) is the amount of data transferred from auxiliary 
storage to the pool to permit instruction execution and as a consequence of set access state, implicit 
access group movement, and internal machine actions. 


The amount of the pool not assigned to virtual addresses represents the storage available to be used 


for new transfers into the main storage poo! without displacing any virtual data already in the pool. 
After a pool’s size has been modified (via the Modify Resource Management Controls instruction), this 
value will be inaccurate until a Modify Resource Management Controls instruction, option hex OD, is 
issued to flush the modified pool. After which time, this value will be accurate until the pool size is 
again modified. The value returned will not include any storage that has been reserved for load/dump 
sessions active in the pool. 


Multiprogramming Level Contro/ information (Hex OA): 


¢ Machine-wide MPL control Char(16) 
— Machine maximum number of MPL classes Bin(2) 
— Machine current number of MPL classes Bin(2) 
— MPL (max) Bin(2) 
— Ineligible event threshold Bin(2) 
— MPL (current) Bin(2) 
— Number of processes in ineligible state Bin(2) 
— Reserved Char(4) 
e MPL class information (repeated for each MPL Char(16) 
class, from 1 to the current number of MPL classes) 
— MPL (max) Bin(2) 
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— Ineligible event threshold Bin(2) 
— Current MPL Bin(2) 
— Number of processes ineligible state Bin(2) 
— Number of processes assigned to class Bin(2) 
— Transitions (active to ineligible) Bin(2) 
— Transitions (active to MI wait) Bin(2) 
— Transitions (MI wait to ineligible) Bin(2) 


Machine-Wide MPL Control: 


Maximum number of MPL classes is the largest number of MPL classes allowed in the machine. 
These are assumed to be numbered from 1 to the maximum. 


Current number of MPL classes is a user-specified value for the number of MPL classes in use. 
They are assumed to be numbered from 1 to the current number. 


MPL (max) is the maximum number of processes which may concurrently be in the active state in 
the machine. 


Ineligible event threshold is a number which, if exceeded by the machine number of ineligible proc- 
esses defined below, will cause the machine ineligible threshold exceeded (hex O00C,04,01) event to 
be signaled. When the event is signaled, this value is set by the machine to 65,535. 


MPL (current) is the current number of processes in the active state. 


Number of processes in the ineligible state is the number of processes not currently active because 
of enforcement of both the machine and class MPL rules. 


MPL Class Information 


MPL class information is data in an array that is associated with an MPL class by virtue of its 
ordinal position within the array. 


MPL (max) is the number of processes assigned to the class which may be concurrently active. 


Ineligible event threshold, MPL (current), and number of processes in ineligible state are as defined 
above but apply only to processes assigned to the class. 


Number of processes assigned to class is the total number of processes, in any state, assigned to 
the pool. 


Transitions count is the total number of transitions by processes assigned to a class as follows: 
1. Active state to ineligible state 
2. Active state to wait 
3. Wait state to ineligible state 


Note that transitions from wait state to active state can be derived as (2 - 3) and transitions from 
ineligible state to active state as (1 + 3). These numbers are Bin(2) and are maintained by the 
machine without regard to overflow conditions. 


Machine Reserved Storage Pool information (Hex OC): 


e Current number of pools Bin(2) 
e Reserved Char(6) 
e Individual main storage pool information Char(16) 
(repeated once for each pool, up to the current number of pools) 
— Pool size Bin(4) 
— Machine portion of the pool Bin(4) 
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— Number of load/dump sessions Bin(2) 
— Reserved Char(6) 


Pool size is the amount of main storage assigned to the pool (including the machine reserved portion). 


Machine portion of the pool specifies the amount of storage from the pool that is dedicated to machine 
functions. 


User storage area 1? (Hex 11): 
e User data Char(*) 


The user data previously stored internally in the machine through usage of the corresponding option on 
the Modify Resource Management Controls instruction is materialized into the receiver. The operand 1 
template, for this option, must start on a 16 byte boundary and any pointers contained in the user data 

are preserved in the materialization. 


The length value materialized in the number of bytes available for materialization field of operand 1 
specifies the length of the entire operand 1 template and is limited, through checks performed on the 
modify operation, to a maximum value of 65,504 (64K-32) bytes. The actual length of the user data 
materialized is calculated by subtracting 16 from the length value for the total template length. 


Auxiliary Storage Information (Hex 12): 


The auxiliary storage information describes the ASPs (auxiliary storage pools) which are configured 
within the machine and the units of auxiliary storage currently allocated to an ASP or known to the 
machine but not allocated to an ASP. 


Note that contrary to the normal case of being able to modify the values materialized by this option 
through use of the Modify Resource Management Controls instruction, modification of most of the aux- 
iliary storage configuration is performed using functions available in the Dedicated Service Tool (DST). 


Also note that through appropriate setting of the number of bytes provided field for operand 1, the 
amount of information to be materialized for this option can be reduced thus avoiding the processing 
for unneeded information. As an example, by setting this field to only provide enough bytes for the 
common 16 byte header, plus the option Hex 12 control information, plus the system ASP entry of the 
ASP information, you can get just the information up through the system ASP entry returned and avoid 
the overhead for the user ASPs and unit information. 


Control information Char(64) 
(occurs just once) 

¢ Number of ASPs Bin(2) 

¢ Number of allocated auxiliary storage units Bin(2) 


Note: Number of configured, non-mirrored 
units + number of mirrored pairs 


¢ Number of unallocated auxiliary storage units Bin(2) 
¢ Control flags Char(1) 
— Main storage dump area unavailable Bit O 
— Reserved (binary 0) Bits 1-7 
e Reserved (binary 0) Char(1) 
e Maximum unprotected space used Char(8) 
e Current unprotected space in use Char(8) 
e Checksum main storage Bin(4) 
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Number of pairs of mirrored units 
Mirroring main storage 

Reserved (binary 0) 

Total temporary space including LS 
Number of bytes in a page 


Reserved (binary 0) 


ASP information 
(Repeated once for each ASP. Located immediately after the control information above. ASP 1, always 
configured, is first. Configured user ASPs follow in ascending numerical order.) 


ASP number 

ASP control flags 

— Suppress threshold exceeded event 
— User ASP overflow 

— Checksum protection 

— Unprotected space overflow 

— ASP mirrored 

— User ASP MI State 

— ASP overflow storage available 
— Reserved (binary 0) 

ASP overflow recovery result 

— Successful 

— Failed due to insufficient free space 
— Cancelled 

— Reserved (binary 0) 

Reserved (binary 0) 

ASP media capacity 

Reserved 

ASP space available 

ASP event threshold 

ASP event threshold percentage 
Reserved (binary 0) 

ASP system storage 

ASP overflow storage 

Space allocated to the Error log 
Space allocated to the machine log 
Space allocated to the machine trace 
Space allocated for main store dump 


Space allocated to the microcode 


Materialize Resource Management Data (MATRMD) 


Bin(4) 
Bin(2) 
Bin(4) 
Char(2) 
Char(8) 
Bin(4) 
Char(12) 
Char(160) 


Char(2) 
Char(1) 
Bit 0 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Char(‘) 
Bit 0 
Bit 1 
Bit 2 
Bits 3-7 
Char(4) 
Char(8) 
Char(8) 
Char(8) 
Char(8) 
Bin(2) 
Char(6) 
Char(8) 
Char(8) 
Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 
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Reserved 


ASP checksum information . 

— Protected space capacity 

— Unprotected space capacity 
— Protected space available 

— Unprotected space available 


— Unprotected space on each checksummed 


unit 


— Reserved 


Unit information 
(Consists of one entry each for the configured, non-mirrored units and one unit of the mirrored pairs, 


the non-configured units, and the other unit of the mirrored pairs. 


Char(12) 
Char(64) 
Char(8) 
Char(8) 
Char(8) 
Char(8) 
Bin(4) 


Char(28) 


Char(208) 


Materialize Resource Management Data (MATRMD) 


An allocated storage unit (ASU) is either an allocated, non-mirrored unit or a mirrored pair. Note that 
the mirrored pair counts only as one ASU. When used without qualification, the term unit refers to an 
ASU. 


Unit information start may be located by the Unit Information Offset in the control information.) 


Device type 


— Disk Type 
— Disk Model 


Device identification 


— Unit number 
— Serial number 
— Reserved 


Unit relationship 


— Reserved 
— Bus information 
- Bus number 
- Bus unit (IOP) 
— Controller identification 
— Actuator identification 


Unit ASP number 
Logical mirrored pair status 


— Unit mirrored 

— Mirrored unit protected 
— Mirrored pair reported 
— Reserved 


Mirrored unit status 

Unit media capacity 

Unit storage capacity 

Unit space available 

Unit reserved system space 


Unit relationship 


Char(8) 


Char(4) 
Char(4) 


Char(8) 


Char(2) 
Char(4) 
Char(2) 


Char(4) 


Char(1) 
Char(1) 
Bits 0-2 
Bits 3-7 
Char(1) 
Char(1) 


Char(2) 
Char(1) 


Bit O 
Bit 1 
Bits 2 
Bits 3-7 


Char(1) 
Char(8) 
Char(8) 
Char(8) 
Char(8) 
Char(6) 
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— Bus information 
- Bus number 
- Bus unit (IOP) 

— Unit address 
- Controller identification 
- Actuator identification 
- Reserved 


Unit control flags 
— Unit in checksummed ASP 
— Unit is device parity protected 
— Subsystem is active 
— Unit in subsystem has failed 
— Other unit in subsystem has failed 
— Subsystem runs in degraded mode 
— Hardware failure 
— Device parity protection is being rebuilt 
— Unit is not ready 
— Unit is write protect 
— Unit is busy 
— Unit is not operational 
— Status is not recognizable 
— Status is not available 
— Unit is Read/Write protected 
— Reserved (binary 0) 
Bits 2 to 14 are mutually exclusive. 
Reserved 
Unit checksum information 
— Unit redundancy space 
— Unit protected space capacity 
— Unit protected space available 
— Unit unprotected space capacity . 
— Unit unprotected space available 
— Unit checksum set number 
— Reserved (binary Q) 
Unit usage information 
— Blocks transferred to main storage 
— Blocks transferred from main storage 
— Requests for data transfer to main storage 
— Requests for data transfer from main storage 


— Permanent blocks transferred 
from main storage 


Char(2) 
Char(1) 
Char(‘) 
Char(4) 
Char(1) 
Char(1) 
Char(2) 


Char(2) 
Bit 0 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 
Bit 11 
Bit 12 
Bit 13 
Bit 14 
Bit 15 


Char(16) 
Char(64) 
Char(8) 
Char(8) 
Char(8) 
Char(8) 
Char(8) 
Char(2) 
Char(22) 
Char(64) 
Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 
Bin(4) 
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— Requests for permanent data transfer Bin(4) 
from main storage 

— Redundancy blocks transferred Bin(4) 
from main storage 

— Requests for redundancy data transfer from Bin(4) 
main storage 

— Reserved (binary 0) Char(32) 


Number of ASPs is the number of ASPs configured within the machine. One, the minimum value, indi- 
cates just the system ASP exists and that there are no user ASPs configured. Up to 15 user ASPs can 
be configured. Values greater than one indicate how many user ASPs are configured in addition to the 
system ASP. The system ASP always exists. 


Number of allocated auxiliary storage units is the number of configured units logically addressable by 
the system as units. This is the number of configured, non-mirrored units plus the number of mirrored 
pairs allocated to the ASPs. The total number of units (actuator arms) on the system is the sum of the 
allocated auxiliary storage units plus the number of unallocated auxiliary storage units plus the 
number of pairs of mirrored units. For example, each 9335 enclosure represents two units. Informa- 
tion on these units is materialized as part of the unit information. Any two units of the same type and 
size may be associated to form a mirrored pair. Association of two units as a mirrored pair reduces 
the amount of logically available storage by the number of bytes contained on one of the mirrored 
units in the mirrored pair. 


Number of unallocated auxiliary storage units is the number of auxiliary storage units that are currently 
not allocated to an ASP. Information on these units is materialized as part of the unit information. 


The main storage dump area unavailable flag indicates whether or not the main storage dump area on 
disk is unavailable. A value of binary 1 indicates it is unavailable; binary 0 indicates it is available. 
The condition where it is unavailable can arise when main storage is added to the machine, but during 
subsequent IPL processing the machine can not free up space on the load source disk unit for the 
additional dump area needed. This occurs when there is insufficient space available on the other disk 
units in the system ASP to allow for movement of object allocations off of the load source unit. The 
corrective action is to free up space in the system ASP and relPL the machine so the allocation of 
additional space to the dump area can be completed. 


The main storage dump area is important for recovery and diagnostic purposes. It is used by the 
machine during certain hardware and power failures to capture a main storage dump which is used to 
minimize the object damage which can result. It is also used by the machine during certain software 
logic failures to capture a main storage dump which is used to determine the cause of the failure. 


Maximum unprotected space used (Checksum field) is the largest number of bytes of unprotected 
storage used at any one time since the last IPL of the machine. When checksum protection is not in 
effect for the system ASP, this field describes the amount of unprotected storage that would have been 
used if checksum protection had been in effect. 


Current unprotected space used (Checksum field) is the current number of bytes of unprotected storage 
in use. When checksum protection is not in effect for the system ASP, this field describes the amount 
of unprotected storage that would be in use if checksum protection was in effect. 


Checksum main storage (Checksum field) is the number of bytes of main storage reserved in the 
machine storage pool for checksum usage. 


Unit information offset is the offset, in bytes, from the start of the operand 1 materialization template to 
the start of the unit information. This value can be added to a space pointer addressing the start of 
operand 1 to address the start of the unit information. 
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Number of pairs of mirrored units represents the number of mirrored pairs in the system. Each mir- 
rored pair consists of two mirrored units; however, only one of the two mirrored units is guaranteed to 
be operational. 


Mirroring main storage is the number of bytes of main storage in the machine storage pool used by 
mirroring. This increases when mirror synchronization is active. This amount of storage is directly 
related to the number of mirrored pairs. 


Total temporary space including LS is the number of bytes of temporary storage allocated on the 
system. This includes the temporary storage allocated on the load source unit. 


Number of bytes in a page is the number of bytes in a single page. This can be used to convert fields 
that are given in pages into the correct number of bytes. 


ASP information is repeated once for each ASP configured within the machine. The number of ASPs 
configured is specified by the number of ASPs field. ASP 1, the system ASP is materialized first. 
Because the system ASP always exists, its materialization is always available. The user ASPs which 
are configured are materialized after the system ASP in ascending numerical order. There may be 
gaps in the numerical order. That is, if just user ASPs 3 and 5 are configured, only information for 
them is materialized producing information on just ASP 1, ASP 3 and ASP 5 in that order. 


ASP number uniquely identifies the auxiliary storage pool. The ASP number may have a value from 1 
through 16. A value of 1 indicates the system ASP. A value of 2 through 16 indicates a user ASP. 


Suppress threshold exceeded event flag indicates whether or not the machine is suppressing signaling 
of the related event when the event threshold in effect for this ASP has been exceeded. A value of 
binary 1 indicates that the signaling is being suppressed; binary 0 indicates that the signaling is not 
being suppressed. The default after each IPL of the machine is that the signaling is not suppressed; 
i.e. default is binary 0. For the system ASP, this flag is implicitly set to binary 1 by the machine when 
the machine auxiliary storage threshold exceeded (hex 000C,02,01) event is signaled. For a user ASP, 
this flag is implicitly set to binary 1 by the machine when the user auxiliary storage threshold exceeded 
(hex 000C,02,02) event is signaled. This is done to avoid repetitive signaling of the event when the 
threshold exceeded condition occurs. Option Hex 12 of the Modify Resource Management Controls 
instruction can be used to explicitly reset the suppression of the threshold exceeded event when it is 
desirable to again have the machine detect the threshold exceeded condition and signal the related 
event. 


User ASP overflow flag (Checksum field) indicates whether or not object allocations directed into the 
user ASP have overflowed into the system ASP. A value of binary 1 indicates overflow; binary 0 indi- 
cates no overflow. This flag does not apply to the system ASP, and is always set to a binary 0 for it. 


Checksum protection flag specifies whether or not the ASP is under checksum protection. A value of 
binary 1 indicates that checksum protection is in effect; a value of binary 0 indicates it is not. 


Unprotected space overflow flag (Checksum field) specifies whether or not allocations for unprotected 
data in the ASP have exceeded the unprotected space capacity and overflowed into the area normally 
used for allocation of protected data. A value of binary 1 indicates that such overflow has occurred; a 
value of binary 0 indicates it has not. This status is set when the ASP unprotected space overflow(hex 
O00C,02,04) event is signaled; it is reset automatically on the subsequent IMPL of the machine. 
Because unprotected storage is used primarily for allocation of temporary objects which are automat- 
ically deallocated as part of the IPL process, the overflowed allocations are freed up at IPL, providing 
for the automatic reset of the overflow condition. Because unprotected storage is only allowed for the 
system ASP, this flag is only applicable to the system ASP. 


ASP mirrored flag specifies whether or not the ASP is configured to be mirror protected. A value of 
binary 1 indicates that ASP mirror protection is configured. Refer to the mirror unit protected flag to 
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determine if mirror protection is active for each mirrored pair. A value of binary 0 indicates that none 
of the units associated with the ASP are mirrored. 


User ASP MI State indicates the state of the User ASP. A value of binary 1 indicates that the User ASP J 
is in the ‘new’ state. This means that a context may be allocated in this User ASP. A value of binary 0 

indicates that the User ASP is in the ‘old’ state. This means that there are no contexts allocated in this 

User ASP. This flag has no meaning for the System ASP and will always be set to binary 0 for it. 


ASP overflow storage available flag indicates whether or not the amount of auxiliary storage that has 
overflowed from the user ASP into the system ASP is available. A value of binary 1 indicates that the 
amount is maintained by the machine and available in the ASP overflow storage field. A value of 
binary 0 indicates that the amount is not available. 


ASP overflow recovery result flags indicate the result of the ASP overflow recovery operation which is 
performed during an IPL upon request by the user. When this operation is requested, the machine 
attempts to recover the user ASP from an overflow condition by moving overflowed auxiliary storage 
from the system ASP back to the user ASP during the Storage Management recovery step of an IPL. 
The successful flag is set to a value of binary 1 when all the overflowed storage was successfully 
moved. The failed due to insufficient free space flag is set to a value of binary 1 when there is not 
sufficient free space in the user ASP to move all the overflowed storage. The cancelled flag is set to a 
value of binary 1 when the operation was cancelled prior to completion (e.g., system power loss, user 
initiated |PL). 


ASP media capacity specifies the total space, in number of bytes of auxiliary storage, on the storage 
media allocated to the ASP. This is just the sum of the unit media capacity fields for (1) the units 
allocated to the ASP or (2) the mirrored pairs in the ASP. 


ASP space available is the number of bytes of auxiliary storage that is not currently assigned to objects << 
or internal machine functions, and therefore, is available for allocation in the ASP when the ASP is not J 
under checksum protection. Note that a mirrored pair counts for only one unit. When the ASP is under 
checksum protection, this value is meaningless and the ASP checksum information describes the 

space available values. 


ASP event threshold specifies the minimum value for the number of bytes of auxiliary storage available 
in the ASP prior to the signaling of the appropriate threshold exceeded event. The threshold exceeded 
condition occurs when either the protected space available value or the ASP space available value, 
depending upon whether checksum protection is or isn’t in effect for the ASP, becomes equal to or less 
than the ASP event threshold value. This condition causes either the auxiliary storage threshold 
exceeded (hex O00C,02,01) event, for the system ASP, or the user ASP threshald exceeded event (hex 
O000C,02,02), for a user ASP, to be signaled. Redundant signaling of these events is suppressed as 
indicated by the setting of the suppress threshold exceeded event flag. Refer to the definition of the 
suppress threshold exceeded event flag for more information. 


The ASP event threshold value is calculated from the the ASP event threshold percentage value by 
multiplying either the protected space capacity value or the ASP media capacity value, depending 

upon whether checksum protection is or isn’t in effect for the ASP, by the ASP event threshold per- 
centage and subtracting the product from that same capacity value. 


~ 


ASP event threshold percentage specifies the auxiliary storage space utilization threshold as a per- 
centage of either the protected space capacity or the ASP media capacity, depending upon whether 
checksum protection is or isn’t in effect for the ASP. This value is used, as described above, to calcu- 
late the ASP event threshold value. This value can be modified through use of Dedicated Service Tool 
DASD configuration options. 
2) 


ASP system storage specifies the amount of system storage currently allocated in the ASP in bytes. 
This storage will not be calculated when determining if the user ASP MI state can be changed. 
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ASP overflow storage indicates the number of bytes of auxiliary storage that have overflowed from the 
user ASP into the system ASP. This value is valid only if the ASP overflow storage available flag is set 
to a value of binary 1- : 


Space allocated to the Error log this is the number of pages of auxiliary storage that are allocated to 
the error log. This field only applies to the System ASP. 


Space allocated to the machine log this is the number of pages of auxiliary storage that are allocated 
to the machine log. This field only applies to the System ASP. 


Space allocated to the machine trace this is the number of pages of auxiliary storage that are allocated 
to the machine trace. This field only applies to the System ASP. 


Space allocated for Main Store Dump this is the number of pages of auxiliary storage that are allocated 
to the main store dump space. The contents of main store are written to this location for some system 
terminations. This field only applies to the System ASP. 


Space allocated to microcode this is the number of pages of auxiliary storage that are allocated for 
microcode and space used by the microcode. The space allocated to the error log, machine log, 
machine trace, and main store dump space is not included in this field. This field only applies to the 
System ASP. 


ASP checksum information (Checksum field) specifies capacity and space available values that apply 
when the ASP is under checksum protection. In this case, the units of auxiliary storage allocated to 
ASP are formatted with areas for protected data, unprotected data, and redundancy data. Information 
on the protected and unprotected space is provided both here in these fields on an ASP basis and 
under unit information on a per unit basis. Information on redundancy space is only provided under 
unit information on a per unit basis. When the ASP is not under checksum protection, the values of 
these fields are meaningless. 


Protected space capacity (Checksum field) specifies the total number of bytes of auxiliary storage for- 
matted for the storage of protected data in the ASP. 


Unprotected space capacity (Checksum field) specifies the total number of bytes of auxiliary storage 
formatted for storage of unprotected data in the ASP. Since unprotected space is only allowed in the 
system ASP, this information is only applicable to the system ASP. 


Protected space available (Checksum field) specifies the number of bytes of auxiliary storage formatted 
for storage of protected data that are not currently assigned to objects or internal machine functions, 
and therefore, are available for allocation in the ASP. 


Unprotected space available (Checksum field) specifies the number of bytes of auxiliary storage for- 
matted for storage of unprotected data that are not currently assigned to objects or internal machine 
functions, and therefore, are available for allocation in the ASP. Since unprotected space is only 
allowed in the system ASP, this information is only applicable to the system ASP. 


Unprotected space on each checksummed unit (Checksum field) specifies the number of megabytes 
(millions of bytes) of auxiliary storage formatted for storage of unprotected data on each unit allocated 
to a checksum set in the ASP. Using the Dedicated Service Tool to modify this value provides for 
altering the relation of the protected versus unprotected space capacity values. Since unprotected 
space is only allowed in the system ASP, this information is only applicable to the system ASP. 
Unit information is materialized in the following order: 

Group 1: Configured units consisting of non-mirrored units and mirrored units. 


Group 2: Non-configured units 
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Group 3: Configured units consisting of mirrored units. 


The unit information is located by the unit information offset field which specifies the offset from the 
beginning of the operand 1 template to the start of the unit information. The number of entries for each J 
of the three groups listed above is defined as follows: 


Group 1: Number of non-mirrored, configured units + number of mirrored pairs 
Group 2: Number of non-configured storage units 
Group 3: Number of mirrored pairs 


For unallocated units, the device type, device identification, unit relationship, and unit media capacity 
fields contain meaningful information. The remaining fields have no meaning for unallocated units 
because the units are not currently in use by the system. Mirrored unit entries contain either current 
or last known information. The last known data consists of the mirrored unit status, disk type, disk 
model, unit ASP number, disk serial number, and unit address. Last known information is provided 
when the Mirrored Unit Reported field is a binary zero. 


Disk type identifies the type of disk enclosure containing this auxiliary storage unit. This is the four byte 
character field from the vital product data for the disk device which identifies the type of drive. For 
example, the value is character string ’9332’ for a 9332 device and ‘9335’ for a 9335 device. 


Disk model identifies the model of the type of disk enclosure containing this auxiliary storage unit. This 
is the four byte character field from the vital product data for the disk device which identifies the model 
of the drive. For example, the value is character string ‘0200’ for a model 200 9332 device and ‘0400’ for 
a model 400 9332 device. 


Unit number uniquely identifies each non-mirrored unit or mirrored pair among the configured units. 

Both mirrored units of a mirrored pair have the same unit number. The value of the unit number is 
assigned by the system when the unit is allocated to an ASP. For unallocated units, the unit number is .) 
set to binary zero. 


Serial number specifies the serial number of the device containing this auxiliary storage unit. This is 
the four byte serial number field from the vital product data for the disk device. 


Bus number identifies the |/O Bus to which the disk device containing this auxiliary storage unit is 
connected. 


Bus unit (IOP) identifies the |/O Processor used to access the controller for the disk device containing 
this auxiliary storage unit. 


Controller identification specifies the controller for the disk device containing this auxiliary storage unit. 


Actuator identification specifies the actuator associated with this auxiliary storage unit in the disk 
device containing it. 


Unit ASP number specifies the ASP to which this unit is currently allocated. A value of 1 specifies the 
system ASP. A value from 2 through 16 specifies a user ASP and correlates to the user ASP number 
field in the user ASP information entries. A value of 0 indicates that this unit is currently unallocated. 


Unit mirrored flag indicates that this unit number represents a mirrored pair. This bit is materialized 
with both mirrored units of a mirrored pair. 


Mirrored unit protected flag indicates the mirror status of a mirrored pair. A value of 1 indicates that 

both mirrored units of a mirrored pair are active. AO indicates that one mirrored unit of a mirrored 

pair is not active. Active means that both units are on line and fully synchronized (ie. the data is iden- s) 
tical on both mirrored units). 
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Mirrored unit reported flag indicates that a mirrored unit reported as present. The mirrored unit 
reported present during or following IMPL. Current attachment of a mirrored unit to the system cannot 
be inferred from this bit. A Q indicates that the mirrored unit being materialized is missing. The last 
known information pertaining to the missing mirrored unit is materialized. A 1 indicates that the mir- 
rored unit being materialized has reported. The information for this reported unit is current to the last 
time it reported status to the system. 


Mirrored unit status indicates mirrored unit status. 


A value of 1 indicates that this mirrored unit of a mirrored pair is active (ie. on-line with current 
data). 


A value of 2 indicates that this mirrored unit is being synchronized. 
A value of 3 indicates that this mirrored unit is suspended. 


Mirrored unit status is stored as binary data and is valid only when the unit mirrored flag is on. 


Unit media capacity is the space, in number of bytes of auxiliary storage, on the non-mirrored unit or 
mirrored pair, that is, the capacity of the unit prior to any formatting or allocation of space by the 
system it is attached to. For a mirrored pair, this space is the number of bytes of auxiliary storage on 
either one of the mirrored units. The space is identical on both of the mirrored units. Caution, do not 
attempt to add the capacities of the two units of a mirrored pair together. 


Unit space available is the number of bytes of secondary storage space that is not currently assigned 
to objects or internal machine functions, and therefore, is available for allocation on the unit (or the 
mirrored pair) when the ASP containing it is not under checksum protection. When the ASP containing 
the unit is under checksum protection, this value is meaningless and the Unit checksum information 
describes the space available values. For a mirrored pair, this space is the number of bytes of auxil- 
lary storage available on either one of the mirrored units. The space is identical on both of the mir- 
rored units. Caution, do not attempt to add the capacities of the two units of a mirrored pair together. 


Unit reserved system space is the total number of bytes of auxiliary storage on the unit reserved for 
use by the machine. This storage is not available for storing objects, redundancy data, and other 
internal machine data. When the unit is not in a checksum set, the unit checksum set number contains 
a value of zero, this reserved space is included in the ASP and unit media capacity fields and reduces 
the corresponding space available values. When the unit is in a checksum set, the unit checksum set 
number is nonzero, this reserved space is not included in the ASP and unit checksum information 
fields which provide capacity and space information and, therefore, does not reduce the corresponding 
space available values. 


Bus number identifies the I/O Bus to which the disk device containing this auxiliary storage unit is 
connected. 


Bus unit (IOP) identifies the I/O Processor used to access the controller for the disk device containing 
this auxiliary storage unit. 


Controller identification specifies the controller for the disk device containing this auxiliary storage unit. 


Actuator identification specifies the actuator associated with this auxiliary storage unit in the disk 
device containing it. 


Unit in checksummed ASP - a value of 1 indicates that this unit is configured in an ASP that is 
checksummed. It does not indicate whether or not the unit is in a checksum set. 


Unit is device parity protected - a value of 1 indicates that this unit is device parity protected. 


Subsystem is active indicates whether the array subsystem is active. 
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lf the unit in subsystem has failed field is 1, the unit in an array subsystem being addressed has failed. 
Data protection for this subsystem is no longer in effect. 


If the other unit in subsystem has failed field is 1, the unit being addressed is operational, but another J 
unit in the array subsystem has failed. Data protection for this subsystem is no longer in effect. 


lf the subsystem runs in deqraded mode field is 1, the array subsystem is operational and data pro- 
tection for this subsystem is in effect, but a failure that may affect performance has occurred. It must 
be fixed. 


lf the hardware failure field is 1, the array subsystem is operational and data protection for this sub- 
system is in effect, but hardware failure has occurred. It must be fixed. 


If the device parity protection is being rebuilt field is 1, the device parity protection for this device is 


being rebuilt following a repair action. 

If the unit is not ready field is 1, the unit being addressed is not ready for I/O operation. 

If the unit is write protected field is 1, the write operation is not allowed on the unit being addressed. 
If the unit is busy field is 1, the unit being addressed is busy. 


If the unit is not operational field is 1, the unit being addressed is not operational. The status of the 
device is not known. 


If the unit is not recognizable field is 1, the unit being addressed has an unexpected status. l.e. the 
unit is operational, but its status returned to Storage Management from IOP is not one of those previ- 
ously described. ( 


If the status is not available field is 1, the machine is not able to communicate with I/O processor. The J 
status of the device is not known. 


If the unit is Read/Write protected is 1, a DASD array may be in the read/write protected state when 
there is problem, such as cache problem, configuration problem, or some other array problems that 
could create a data integrity exposure. 


Unit checksum information (Checksum field) specifies capacity and space available values that apply 
when the ASP containing the unit is under checksum protection. In this case, when the unit is in a 
checksum set, the unit checksum set number is nonzero, the unit is formatted with areas for protected 
data, unprotected data, and redundancy data and these fields provide information relating to those 
areas. lf the unit is not allocated to a checksum set, the unit checksum set number contains a value of 
zero, it is only formatted for the storage of unprotected data and the other capacity values will be zero. 
When the ASP containing the unit is not under checksum protection, the values of these fields are 
meaningless, except that the unit checksum set number field will contain a zero value. 


Unit redundancy space (Checksum field) is the total number of bytes of auxiliary storage on the unit 
formatted for use for redundancy data. This storage is not available for storing objects and other 
internal machine data. 


Unit protected space capacity (Checksum field) is the number of bytes of auxiliary storage formatted for 
storage of protected data on the unit. This field is only nonzero if this unit is allocated to a checksum 
set. Units not allocated to a checksum set contain no protected storage area. This value does not 
include the size of any data redundancy area which may have been formatted on the unit as well. 


Unit protected space available (Checksum field) is the number of bytes of protected space on sec- .) 


ondary storage available for allocation on the unit; that is, not currently assigned to objects or internal 
machine functions. This field is only nonzero if this unit is allocated to a checksum set. Units not 


Chapter 19. Resource Management Instructions 19-24 


c 


Materialize Resource Management Data (MATRMD) 


allocated to a checksum set contain no protected storage area, unless they are mirrored. All space of 
a mirrored pair is protected. 


‘Unit unprotected space capacity (Checksum field) is the number of bytes of auxiliary storage formatted 
for storage of unprotected data on the unit. This value does not include the size of any data redun- 
dancy area which may have been formatted on the unit as well. Since unprotected space is only 
allowed in the system ASP, this information is only applicable to units allocated to the system ASP. 


Unit unprotected space available (Checksum field) is the number of bytes of unprotected space on sec- 
ondary storage that are not currently assigned to objects or internal machine functions, and therefore, 
are available for allocation on the unit. Since unprotected space is only allowed in the system ASP, 
this information is only applicable to units allocated to the system ASP. 


Unit checksum set number (Checksum field) specifies the checksum set to which this unit is currently 
allocated. A nonzero value specifies the number of the checksum set. A zero value specifies that the 
unit is currently not assigned to a checksum set. 


Unit usage information specifies statistics relating to usage of the unit. For unallocated units, these 
fields are meaningless. 


Blocks transferred to/from main storage flelds specify the number of 512-byte blocks transferred for the 
unit since the last IMPL. These values wrap around to zero and continue counting in the case of an 
overflow of the field with no indication of the overflow having occurred. 


Requests for data transfer to/from main storage fields specify the number of data transfer (I/O) 


requests processed for the unit since the last IMPL. These values wrap around to zero and continue 
counting in the case of an overflow of the field with no indication of the overflow having occurred. 
These values are not directly related to the number of blocks transferred for the unit because the 
number of blocks to be transferred for a given transfer request can vary greatly. 


Permanent blocks transferred from main storage specifies the number of 512-byte blocks of permanent 
data transferred from main storage to auxiliary storage for the unit since the last IMPL. In the case of 
an overflow of the field, this value wraps around back to zero and continues counting, with no indi- 
cation of the overflow condition having occurred. 


Requests for permanent data transfer from_main storage specifies the number of transfer (I/O) requests 


for transfers of permanent data from main storage to auxiliary storage that have been processed for 
the unit since the last IMPL. In the case of an overflow of the field, this value wraps around back to 
zero and continues counting, with no indication of the overflow condition having occurred. This value 
is not directly related to the permanent blocks transferred from main storage value for the unit ASP 
because the number of blocks to be transferred for any particular transfer request can vary greatly. 


Redundancy blocks transferred from main storage (Checksum field) specifies the number of 512-byte 
blocks of redundancy data transferred from main storage to auxiliary storage for the unit since the last 
IMPL. In the case of an overflow of the field, this value wraps around back to zero and continues 
counting, with no indication of the overflow condition having occurred. This field is only meaningful for 
a unit in a checksum set. 


x 


Requests for redundancy data transfer from main storage (Checksum field) specifies the number of 


transfer (I/O) requests for transfers of redundancy data from main storage to auxiliary storage that 
have been processed for the unit since the last IMPL. In the case of an overflow of the field, this value 
wraps around back to zero and continues counting, with no indication of the overflow condition having 
occurred. This value is not directly related to the redundancy blocks transferred from main storage 
value for the unit because the number of blocks to be transferred for any particular transfer request 
can vary greatly. This field is only meaningful for a unit in a checksum set. 
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Multiprocessor utilizations (Hex 13): 


¢ Number of processors configured on Bin(2) 
the machine 

e Number of configured processors Bin(2) 
currently active on the machine 

e Bit map of processors currently active Char(2) 
on the machine 
— Processor 1 is active Bit 0 
— Processor 2 is active Bit 1 
— Processor 3 is active Bit 2 
— Processor 4 is active Bit 3 
— Processor 5 is active Bit 4 
— Processor 6 is active Bit 5 
— Processor 7 is active Bit 6 
— Processor 8 is active Bit 7 
— Processor 9 is active Bit 8 
— Processor 10 is active Bit 9 
— Processor 11 is active _Bit 10 
— Processor 12 is active Bit 11 
— Processor 13 is active Bit 12 
— Processor 14 is active Bit 13 
— Processor 15 is active Bit 14 
— Processor 16 is active Bit 15 

« Reserved Char(2) 

¢« Array of CHAR(8) processor time used Char(128) 
since IPL values. Repeated once for each active processor. 
— Processor 1 time busy since IPL Char(8) 
— Processor 2 time busy since IPL Char(8) 
— Processor 3 time busy since IPL Char(8) 
— Processor 4 time busy since IPL — Char(8) 
— Processor 5 time busy since IPL Char(8) 
— Processor 6 time busy since /PL Char(8) 
— Processor 7 time busy since IPL Char(8) 
— Processor 8 time busy since IPL Char(8) 
— Processor 9 time busy since IPL Char(8) 
— Processor 10 time busy since IPL Char(8) 
— Processor 11 time busy since IPL Char(8) 
— Processor 12 time busy since IPL Char(8) 
— Processor 13 time busy since IPL Char(8) 
— Processor 14 time busy since IPL Char(8) 
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— Processor 15 time busy since IPL Char(8) 


— Processor 16 time busy since IPL Char(8) 


The number of active processors will always be less than or equal to the number of configured 
processors. The active processor bit map will only indicate active processors within the first (leftmost) 


number of configured processors number of bits. The significance of bits within the time busy fields 
are the same as that defined for the time-of-day clock. This option always returns a number of bytes 
available for materialization equal to the length of the entire structure detailed above (it does not vary 
with the number of configured or active processors). 


Storage pool tuning (Hex 14): 


e Control information Char(16) 
(occurs just once) 
e Current number of pools Bin(2) 
e Reserved (binary 0) Char(14) 
Pool information Char(104) 


(repeated once for each pool) 


Type of pool tuning Char(1) 
— Hex 00 = No tuning is being done for the pool 

— Hex 10 = Static tuning 

— Hex 20 


— Hex 30 = Dynamic tuning of transfers to main storage and to auxiliary storage 


Dynamic tuning of transfers to main storage 


Changed page handling Char(1) 
— Hex 00 = System page replacement algorithm handles changed pages 


— Hex 10 = Periodically transfer changed pages to auxiliary storage 


Reserved (binary 0) Char(14) 
Nondatabase objects Char(8) 
— Blocking factor Char(2) 


- Hex 0000 = Use the default system value 
- Hex 0008 = Transfer data between main storage and auxiliary in blocks of 4K. 
- Hex 0010 = Transfer data between main storage and auxiliary in blocks of 8K. 


- Hex 0020 = Transfer data between main storage and auxiliary in blocks of 16K. 


- Hex 0040 = Transfer data between main storage and auxiliary in blocks of 32K. 
— Reserved (binary 0) Char(6) 
Reserved (binary 0) Char(16) 
Handling of database objects by class Char(8) 
(repeat for each of the four classes). 
— Blocking factor Char(2) 

- Hex 0000 = Use the default system value 


- Hex 0008 = Transfer data between main storage and auxiliary in blocks of 4K. 
- Hex 0010 = Transfer data between main storage and auxiliary in blocks of 8K. 


- Hex 0020 = Transfer data between main storage and auxiliary in blocks of 16K. 
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- Hex 0040 = Transfer data between main storage and auxiliary in blocks of 32K. 


- Hex 0080 = Transfer data between main storage and auxiliary in blocks of 64K. 


| 
| 
| - Hex 0100 = Transfer data between main storage and auxiliary in blocks of 128K. 
| — Allow exchange operations Char(1) 


- Hex 00 = Use the default system value 


- Hex C5 = Allow exchange operations 
- Hex D5 = Disable exchange operations 
- Hex D9 = Indicate that objects are good candidates for replacement 
— Handling of requests to transfer object Char(1) 


to auxiliary storage 


- Hex DS = Use the system page replacement algorithm 


- Hex D7 = Purge the objects from main storage 


- Hex D9 = Indicate the objects are good candidates for replacement 
- Hex E6 = Write the objects to auxiliary storage 
— Reserved (binary 0) Char(4) 


| 
| 
| 
| 
| 
| 
| - Hex 00 = Use the default system value 
| 
| 
| 
| 
| 
| 


¢« Reserved (binary 0) Char(32) 


| Current number of pools is a user-specified value for the number of storage pools the user wishes to 
| utilize. These are assumed to be numbered from 1 to the number specified. This number is fixed by 
| the machine to be equal to the maximum number of pools. 


Type of pool tuning determines what the system is doing to tune the performance of a storage pool. 


When tuning is not being done for a pool (hex 00), the system tries to minimize the amount of main 
storage that is used by each of the jobs in the system independent of the amount of main storage 
that exists in a pool. The values returned for nondatabase objects and database objects by class 
will be all zeros to represent that the default values are being used. 


| 

| 

| 

| 

| 

| If static tuning is being done. (hex 10), the system wil! use the values specified for pool information 
| to determine the amount of data to transfer to main storage and auxiliary storage. The values 

| returned for database objects by class and nondatabase objects will be the values previously spec- 
| ified on the MODRMC instructions. 
| 

| 

| 

| 

| 

| 

| 

| 

| 

| 


When dynamic tuning of transfers to main storage is being done (hex 20), the system bases the 
amount of data to transfer to main storage based on the demand for storage in the storage pool, 
the size of the pool, the number of active users in the pool and other performance attributes. The 
values returned for database objects by class and nondatabase objects is the current value being 
used by the system to handle the objects. 


When dynamic tuning of transfers to main storage and auxiliary storage is being done (hex 30), the 
system bases the amount of data to transfer to main storage and to auxiliary storage based on the 
demand for storage in the storage pool, the size of the pool, the number of active users in the pool 
and other performance attributes. The values returned for database objects by class and nondata- 
base objects is the current value being used by the system to handle the objects. 


| When tuning is requested (hex 10, 20 or 30), the system periodically categorizes database objects into 
| four different performance classes. The class are: 
| 
| 


Class 1 Object access appears to be very random - a disk access is required for nearly each record 
that is accessed 
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Class 2. Some locality of reference detected. several records are being accessed per disk access 


Class 3 High locality of reference detected, object is being processed in a sequential manner. refer- 
ences are highly clustered, large portions of the object are resident in memory. 


Class 4 = See following explanation. 


The class of a database object is adjusted if the objects size is small in comparision to the available 
storage in the storage pool. This class adjustment involves adding 1 to the class number, so a class 3 
database object (as defined above) would be treated as a class 4 if it is small in comparision to the 
available storage in the storage pool. 


Reference information for determining a object’s class is collected periodically and by storage pool so 
an object’s class will vary over time and by storage pool. 


Change page handling effects when the system will write changed pages to auxiliary storage. When 
the system page replacement algorithm (hex 00) is specified as the change page handing mechanism, 
the system will transfer changed pages to auxiliary storage when: 


e Explictly requested to transfer the page (for example, Set Access State (SETACST) instruction) 
e There is a demand for pages in the pool 


When the periodically transfer changed pages option (hex 10) is specified as the change page handing 
mechanism, the system will transfer changed pages to auxiliary storage when: 


e Explictly requested to transfer the page (for example, Set Access State (SETACST) instruction) 
e There is a demand for pages in the pool 


e Periodically look for changed pages in a pool and transfer the changed pages to auxiliary storage 


Blocking factor determines how much data should be brought into main storage when the objects is 
needed in main storage. 


Allow exchange operations controls which method the system should use to find main storage to hold 
data. With the exchange method (hex C5), the system uses the page frames associated with a specific 
object to satisfy the request. If exchange operations are disabled (hex D5), the system will use the 
normal page replacement algorithm to find page frames for the request. If objects should be treated as 
good candidates for replacement (hex D9), the system makes the page frames associated with the 
object being exchanged a good replacement candidate but uses the normal page replacement algo- 
rithm to find page frames for the request. 


Handling of requests to transfer objects to auxiliary storage determines when the data is transferred to 


auxiliary storage and when the page frames containing the object are available to contain other data. 
If purging is active (nex D7) and a request is made to purge the object to auxiliary storage, the system 
will immediately schedule the request to transfer the data and when the transfer is completed, the 
page frames containing the data just written will be made available to hold other objects. If writing is 
active (hex E6) and a request is made to purge the object to auxiliary storage, the system will imme- 
diately schedule the request to transfer the data and the page frames are not made good candidates to 
be reused. If objects are good candiates for replacement (hex D9), the objects are likely to be removed 
from main storage by transfering the objects to auxiliary storage when the system needs to transfer 
other objects into main storage. If the system page replacement algorithm is used (hex D5), the system 
decides when the object should be transferred from main storage to auxiliary storage. 


Exceptions 

Operands 
Exception 1 2 Other 
06 Addressing 
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Me Materialize Resource Management Data (MATRMD) 


Operands 
Exception Other 


01 space addressing violation 


02 boundary alignment 


03 range 


x KK Ko 
x KK KN 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X 


10 Damage encountered 
04 system object damage state X X 
44 partial system object damage X X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check X 


22 Object access 
01 object not found X X 


x< 
x< 


02 object destroyed 
03 object suspended X X 


veal 


08 object compressed X . } ' 


24 Pointer specification 
01 pointer does not exist X X 
02 pointer type invalid X X 


2E Resource control limit 


01 user profile storage limit exceeded X 


32 Scalar specification 
02 scalar attribute invalid X 


03 scalar value invalid X 


36 Space management 


01 space extension/truncation ) X 


38 Template specification 


03 materialization length exception xX 
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Set Access State (SETACST) 


Set Access State (SETACST) 


Op Code (Hex) Operand 1 
0341 Access state tem- 
plate 


Operand f: Space pointer. 


ILE access 


SETACST ( 
access State : space pointer 
) 


Description: The instruction specifies the access state (which specifies the desired speed of access) 
that the issuing process has for a set of objects or subobject elements in the execution interval fol- 
lowing the execution of the instruction. The specification of an access state for an object momentarily 
preempts the machine’s normal management of an object. 


Note: This instruction should be used with caution when the pointer to object entry in the template 
below points to a process space (i.e. static storage, automatic storage, and heap space storage). 
These process spaces may be shared by other programs in the activation group, so explicit access 
management may affect those other programs. 


The Set Access State instruction template must be aligned on a.16-byte boundary. The format is: 


¢ Number of objects to be acted upon Bin(4) 
e Reserved (binary 0) Char(12) 
e Access state specifications Char(32) 


(repeated as many times as necessary) 


— Pointer to object whose 


access state is to be changed 


Space pointer 
or system pointer 


— Access state code Char(‘1) 
— Reserved (binary 0) Char(3) 
— Access state parameter Char(12) 
- Access pool ID Char(4) 
- Space length Bin(4) 
- Operational object size Bin(4) 


Note: This value is returned for some of the access state code options. 


The number of objects field specifies how many objects are potential candidates for access state mod- 
ification. An access state specification is included for each object to be acted upon. 


The pointer to object field identifies the object or space which is to be acted upon. For the space ~ 
associated with a system object, the space pointer may address any byte in the space. This pointer is 
followed by parameters that define in detail the action to be applied to the object. 


Access State 
Code (Hex) 
00 


Function and Required Parameter 
No operations are performed. 


The access state code designates the desired access state. The allowed values are as follows: 
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Access State 
Code (Hex) 
01 


02 


03 


04 


18 


20 


21 


Set Access State (SETACST) 


Function and Required Parameter 
Associated object is moved into main storage (if not already there) synchronously with the 
execution of the instruction. 


Associated object is moved into main storage (if not already there) asynchronously with the 
execution of the instruction. 


Associated object is placed in main storage without regard to the current contents of the 
object. This causes access to secondary storage to be reduced or eliminated. For this 
access state code, a space pointer must be provided. 


Associated object is removed from main storage in a manner which reduces oar eliminates 
access to secondary storage. Content of the object is unpredictable after this operation. For 
this access state code, a space pointer must be provided. 


The object is synchronously ensured (changes written to auxiliary storage) and then removed 
from main storage. 


This option returns a number in the operational object size field. The unit assumed is the 
machine minimum transfer size (page size). The value returned is the total size of the 
opertational parts of the object examined/processed, including the associated space (if there 
is one). 

Note: This number is not the number of pages written or removed, but rather, is the total 
size of the object being processed. Some, all or none of the object may be in mainstore prior 
to the execution of the instruction. 


The space /ength field must be Zero for this operation. The entire associated space, if any, 
will be processed with the rest of the object’s storage. 


The access pool !D field is ignored for this operation. 
The associated pointer to the object must be a system pointer. 


This operation essentially combines the functions of a 10 code followed by asynchronously 
bringing the operational parts of the object into main storage. The object is brought into the 
main storage pool identified by the access poo/ !D field). 


Note: Because this function first removes the object from main storage and then brings it 
into main storage, this can be used to “move” an object from one main storage pool to 
another. 


This option returns a number in the operational object size field. The unit assumed is the 
machine minimum transfer size (page size). The value returned is the total size of the object 
processed. 


Note: If this value is larger than the size of the main storage pool being used, unpredictable 
parts of the object will be resident in the main storage pool following processing. 


A a preceding access code of 40 is ignored for this operation. 


The space /ength field must be zero for this operation. The entire associated space, if any, 
will be processed with the rest of the object’s storage. 


The access pool |D field must be specified for this access code (it must be value 1 though 16, 
decimal) . 


The associated pointer to the object must be a system pointer. 


Associated object attributes are moved into main storage synchronous with the instruction’s 
execution. The associated attributes are the attributes that are common to all system 
objects. The associated pointer to object must be a resolved system pointer. 


The “space length” field is ignored for this access code. 


Associated object attributes are moved into main storage asynchronous with the instruction’s 
execution. The associated attributes are the attributes that are common to all system 
objects. The associated pointer to object must be a resolved system pointer. 


The “space length” field is ignored for this access code. 
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Access State 
Code (Hex) 
22 


23 


30 


31 


41 


80 


81 


: Set Access State (SETACST) 


Function and Required Parameter 

Common associated object attributes plus some specified amount of object-specific attributes 
are moved into main storage synchronous with the instruction’s execution. The common 
associated attributes are the attributes that are common to all system objects. The object- 
specific attributes are attributes that vary fram one object type to another. The amount of 
these attributes brought into main storage is controlled by the space /ength field. 


Note: This use of space /ength is not consistent with the name of the field. For this code, the 
space /ength field does not control the size of any associated space processing, it controls 
the length of object-specific attributes processed. 


The space /ength field works in the following manner: it specifies the amount of storage 
above and beyond the common ojbect attributes which will be synchronously brought into 
storage. Therefore, a space /ength of 0 is valid, and results in an operation identical to 
access code 20. 


The associated pointer to object must be a resolved system pointer. 


Common associated object attributes plus some specified amount of object-specific attributes 
are moved into main storage asynchronous with the instruction’s execution. The common 
associated attributes are the attributes that are common to all system objects. The object- 
specific attributes are attributes that vary from one object type to another. The amount of 
these attributes brought into main storage is controlled by the space /ength field. 


Note: This use of space /ength is not consistent with the name of the field. For this code, the 
space /ength field does not control the size of any associated space processing, it controls 
the length of object-specific attributes processed. 


The space /ength field works in the following manner: it specifies the amount of storage 
above and beyond the common ojbect attributes which will be asynchronously brought into 
storage. Therefore, a space /ength of 0 is valid, and results in an operation identical to 
access code 21. 


The associated pointer to object must be a resolved system pointer. 


The associated space of the object is moved into main storage (if not already there) synchro- 
nously with the execution of the instruction. The space /ength field is honored for this opera- 
tion. The associated pointer to the object must be a system pointer. 


The associated space of the object is moved into main storage (if not already there) asyn- 
chronously with the execution of the instruction. The space /ength field is honored for this 
operation. The associated pointer to the object must be a system pointer. 


Perform no operation on the associated object. The main storage occupied by this object is 
to be used, if possible, to satisfy the request in the next access state specification entry. 
Either a space or system pointer may be provided for this access state code. 


Wait for any previously issued but incomplete hex 81 or hex 91” access state code operations 
to complete. This includes all previous hex 81 and hex 91 operations that may have been 
performed on previous Set Access State instructions within the current process as well as 
those that may have been issued in previous access state specification entries in the current 
instruction. The pointer is ignored for this access state code entry. 


Object should be written and it is not needed in main storage by issuing process. Object is 
written to nonvolatile storage synchronously with the execution of the instruction. Any main 
storage that the object occupied is then marked as to make it quickly available for replace- 
ment. 

Object should be written and it is not needed in main storage by issuing process. Object is 
written to nonvolatile storage asynchronously with the execution of the instruction. Any main 
storage that the object occupied is then marked as to make it quickly available for replace- 
ment. 

If desired, the process can synchronize with any outstanding hex 81 access state operations 
by issuing a hex 41 access state operations either within the current instruction or during a 
subsequent Set Access State instruction. 
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au Set Access State (SETACST) 


Access State 

Code (Hex) Function and Required Parameter 

90 Associated object must be insured, but is still needed in main storage. Object is written to 
nonvolatile storage synchronously with the execution of the instruction. Unlike access state 
codes hex 80 and hex 81, this access state code does not mark any main storage occupied by 
the object as to make it quickly available for replacement. 


91 Associated object must be insured, but is still needed in main storage. Object is written to 
nonvolatile storage asynchronously with the execution of the instruction. Unlike access state 
codes hex 80 and hex 81, this access state code does not mark any main storage occupied by 
the object as to make it quickly available for replacement. 


If desired, the process can synchronize with any outstanding hex 91 access state operations 
by issuing a hex 41 access state operations either within the current instruction or during a 
subsequent Set Access State instruction. 


Access state codes hex 03 and hex 04 may be used for spaces only. The pointer to the object in the 
access state specification must be a space pointer. Otherwise, the pointer type invalid (hex 2402) 
exception is signaled. 


Access state code hex 40 may be used in conjunction with access state codes hex 01, hex 02, or hex 
03. The access state specification entry with access state code hex 40 must immediately precede the 
access state specification entry with access state code hex 01, hex 02, or hex 03 with which it is to be 
combined. The pointer to the object in both entries must be a space pointer. Otherwise, the pointer 
type invalid (hex 2402) exception is signaled. The access state parameter field in the access state spec- 
ification entry with code hex 40 is ignored. The access pool /D and the space /ength in the entry with 
access state code hex 01, hex 02, or hex 03 are used. 


The access pool ID field indicates the desired main storage pool in which the object is to be placed 
(0-16). The storage pool ID entry is treated as a 4-byte logical binary value. When a 0 storage pool ID 
is specified, the storage pool associated with the issuing process is used. 


The space length field designates the part of the space associated with the object to be operated on. If 
the pointer to the object entry is a system pointer, the operation begins with the first byte of the space. 
If the pointer to the object entry is a space pointer that specifies a location, the operation proceeds for 
the number of storage units that are designated. No exception is signaled when the number of refer- 
enced bytes of the space are not allocated. When operations on objects are designated by system 
pointers, this operation is performed in addition to the access state modification of the object. This 
entry is ignored for access state codes hex 20 and hex 21. This entry will be truncated to a maximum 
of 65536 for access state codes immediately following access state code 40. 


The operational object size field is a value which is ignored upon input to the instruction and is set by 
the instruction for access codes 10 and 18. It represents, in units of minimum machine transfer size, 
the total size of the object which could/did participate in the operation. The parts of an object which 
are considered “operational” are decided by the machine and does include the associated space, if 
any. 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 


— Contexts referenced for address resolution 
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Set Access State (SETACST) 


Exceptions 


- Operands 
Exception 1 Other 


04 Access state 


01 access state specification invalid X 


06 Addressing 
01 space addressing violation 
02 boundary alignment 
03 range 


x KK MK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation xX 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 
04 system object damage state X 
05 authority verification terminated due to damaged object X 


44 partial system object damage . Xx xX 


1A Lock state 


01 invalid lock state 4 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check »4 


22 Object access 
01 object not found X 
02 object destroyed 


x 


03 object suspended X 
07 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


x «KK KK 


04 pointer not resolved 


2E Resource control limit 


01 user profile storage limit exceeded X 


36 Space management 


01 space extension/truncation X 
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Set Access State (SETACST) 


Operands 
Exception 1 Other 
38 Template specification ) 
01 template value invalid X 


- 
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Dump Space Management Instructions 


Chapter 20. Dump Space Management Instructions 


This chapter describes all the instructions used for dump space management. These instructions are 
arranged in alphabetical order. For an alphabetic summary of all the instructions, see Appendix A, 
“Instruction Summary.” 


Materialize Dump Space (MATDMPS) ............. 2.0. cee ee ee 20-3 
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Materialize Dump Space (MATDMPS) 


Op Code (Hex) Operand 1 Operand 2 


04DA Receiver Dump space 


Operand ?: Space pointer. 


Operand 2: System pointer. 


ILE access 


MATDMPS ( 


receiver : space pointer 


var dump space : system pointer 


) 


Materialize Dump Space (MATDMPS) 


Description: The current attributes of the dump space specified by operand 2 are materialized into the 
receiver specified by operand 1. 


The template identified by operand 1 must be 16-byte aligned in the space. The format of the 
materialization is as follows: 


Materialization size specification 
— Number of bytes provided for materialization 


— Number of bytes available for materialization 
(always 128 for this instruction) 


Object identification 

— Object type 

— Object subtype 

— Object name 
Object creation options 
— Existence attributes 


0 = Temporary 
1 Permanent 


— Space attribute 


0 = Fixed length 
1 = Variable length 


— Context 


0 = Addressability not in context 
1 = Addressability in context 


— Reserved (binary 0) 
— Initialize space 

— Reserved (binary 0) 
Recovery options 

Size of space 


Initial value of space 


Char(8) 
' Bin(4) 
Bin(4) 


Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(4) 
Bit 0 


Bit 1 


Bit 2 


Bit 3-12 
Bit 13 
Bit 14-31 
Char(4) 
Bin(4) 
Char(1) 
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Materialize Dump Space (MATDMPS) 


¢ Performance class Char(4) 

e Reserved : Char(7) 

* Context System pointer 
« Reserved Char(16) 

« Dump Space size Char(4) 

* Dump data size Char(4) 

¢« Dump data size limit Char(4) 

e Reserved Char(20) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less then eight causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be materialized. 
The instruction materializes as many bytes as can be contained in the area specified as the receiver. 
If the byte area identified by the receiver is greater than that required to contain the information 
requested, then the excess bytes are unchanged. No exceptions are signaled in the event that the 
receiver contains insufficient area for the materialization, other than the materialization length (hex 
3803) exception described previously. 


The dump space size field is set with the current size value for the number of 512-byte blocks of space 
allocated for storage of dump data within the dump space. 


The dump data size field is set with the current size value for the number of 512-byte blocks of dump 
data contained in the dump space. This value specifies the number of blocks from the start of the 
dump space through the block of dump data which has been placed into the dump space at the largest 
dump space offset value. A value of zero indicates that the dump space currently contains no dump 
data. 


The dump data size limit field is set with the current size limit for the number of 512-byte blocks of 
dump data which may be stored in the dump space. A value of zero indicates that no explicit limitation 
is placed on the amount of dump data which may be stored in the dump space. The machine implicitly 
places a limit on the maximum size of a dump space. This value of this limitation is dependent upon 
the specific implementation of the machine. 


Authorization Required 
¢ Operational 

— Operand 2 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
* Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 
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Exception 


06 


08 


0A 


1A 


20 


22 


24 


2E 


32 


36 


38 


Addressing 

01 space addressing violation 

02 boundary alignment violation 
03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 unauthorized for operation 


Damage encountered 
04 system object damage state 
05 authority verification terminated due to damaged object 


44 partial system object damage 


Lock state 


01 invalid lock state 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 

03 object suspended 

07 authority verification terminated due to destroyed object 


08 object compressed 


Pointer specification 
01 pointer does not exist 
02 pointer type invalid 


03 pointer addressing invalid object 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 
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Materialize Dump Space (MATDMPS) 


Operands 
1 2 
X X 
X X 
X X 
X X 
X X 
X 
X 
X 
X X 
X X 
X X 
X X 
X X 
X 
X X 
X 


Other 


*< 


20-5 


Exception 
03 materialization length exception 


Materialize Dump Space (MATDMPS) 


Operands 
1 2 Other 
xX 
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Chapter 21. Machine Observation Instructions 


This chapter describes all instructions used for machine observation. These instructions are arranged 
alphabetically. For an alphabetic summary of all the instructions, see Appendix A, “Instruction 
Summary.” 


Find Relative Invocation Number (FNDRINVN) ...........0..0 0.0000. eee eee eee 21-3 
Materialize Instruction Attributes (MATINAT) ........0..0..0 00.000 00 eee eee eee 21-8 
Materialize Invocation (MATINV) ......0 20.0.0... 0. ee ee 21-14 
Materialize Invocation Attributes (MATINVAT) .........0. 0.0.00. eee ee ee eee 21-18 
Materialize Invocation Entry (MATINVE) ..........0.0. 0.00. 0c eee ee 21-28 
Materialize Invocation Stack (MATINVS) .........0.0 0... 0 2 cee es 21-32 
Materialize: Pointer (MATLPUR)®: 6 #2 <4 2% 4.6 hb oe EA ORE OAR ASD eee Gr ERS 21-37 
Materialize Pointer Locations (MATPTRL) ........... 0.00.0 eee eee eee eee 21-46 
Materialize System Object (MATSOBJ) .. 1... ee 21-48 
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Find Relative Invocation Number (FNDRINVN) 


Find Relative Invocation Number (FNDRINVN) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 


0543 Relative invoca- Search range Search criterion 
tion number template 


Operand ?: Signed binary(4) variable scalar 
Operand 2: Character(48) scalar (fixed length) or null 


Operand 3: Space pointer 


ILE access 
FNDRINVN ( 
var relative _invocation_number : stgned binary; 
var search range : aggregate; OR 


null operand; 
Search criterion_template : space pointer 


Description: The invocations identified by operand 2 are searched in the order specified by operand 2 
until an invocation is found which satisfies the search criterion specified in the operand 3 template. 
The identity of the first invocation (in search order) to satisfy the search criterion is returned in 
operand 1. If no invocation in the specified range satisfies the search criterion, then either an excep- 
tion is signaled, or a value of zero is returned in operand 1, depending on the modifiers specified in 
the operand 3 template. 


Operand 1/ is returned as a signed binary(4) value identifying the first invocation found that satisfies the 
specified search criterion. It is specified relative to the starting invocation identified by operand 2. A 
positive number indicates a displacement in the direction of newer invocations, while a negative indi- 
cates a displacement in the direction of older invocations. A zero value indicates that no invocation in 
the specified range matched the specified criterion. Operand 1 is not modified in the event that the 
instruction terminates with an exception. 


Note that a modifier in the operand 3 template determines if the starting invocation identified by 
operand 2 is to be skipped. If the starting invocation is skipped during the search then a result of zero 
in operand 1 always indicates failure to find an invocation that satisfies the criterion. If the starting 
invocation is not skipped, then a failure to find an invocation that satisfies the criterion results in an 
exception. 


Operand 2 identifies the starting invocation and the range of the search. If operand 2 is specified as a 
null operand, then operand 2 is assumed to identify a range starting with the current invocation and 
proceeding through all existing older invocations. 


Operand 3 is a space pointer to a template that identifies the search criterion and search modifiers for 
the find operation. 


Operand 2: The value specified by operand 2 identifies the range of invocations to be searched. This 
operand can be null (which indicates the range which starts with the current invocation and proceeds 
through all existing older invocations), or it can contain either an invocation pointer to an invocation or 
a null pointer (which indicates a range starting with the current invocation). 


Operand 2 has the following format: 
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Find Relative Invocation Number (FNDRINVN) 


> 
¢ Starting invocation offset Bin(4) 
¢ Originating invocation offset. (ignored) Bin(4) . 
¢ Invocation range Bin(4) J 
¢ Reserved (binary 0) Char(4) 
* Starting invocation pointer Invocation pointer 
« Reserved (binary 0) Char(16) 


If a non-null pointer is specified for starting invocation pointer, then operand 2 must be 16-byte aligned 
in the space. 


Terminology: 


Requesting invocation 
The invocation executing the FNDRINVN instruction. Note that, in many cases, this invoca- 


tion belongs to a system or language run-time procedure/program, and the instruction is 
actually being executed on behalf of another procedure or program. 


Starting invocation 
The invocation which serves as the starting point for the search. 


Field descriptions 


Starting invocation offset 
A signed numerical value indicating an invocation relative to the invocation located by the starting 
invocation pointer. A value of zero denotes the invocation addressed by the starting invocation 
pointer, with increasingly positive numbers denoting increasingly later invocations in the stack, and 
increasingly negative numbers denoting increasingly earlier invocations in the stack. ( 


If the starting invocation pointer is valid or null, but the invocation identified by this offset does not >) 
exist in the stack, an invocation offset outside of current stack (hex 2C1A) exception will be sig- 
naled. 


Originating invocation offset 
This field is used by other instructions but is ignored by FNDRINVN. 


Invocation range 

Invocation range is a signed numerical value which specifies the direction of the search and the 
maximum number of invocations to be examined. The magnitude of invocation range specifies the 
maximum number of invocations to be searched exclusive of the starting invocation. It is not an 
error if this magnitude is greater than the number of existing invocations in the specified direction. 
If the sign of invocation range is positive (and non-zero), the search is performed in the direction of 
newer invocations, while if the sign is negative, the search is performed in the direction of older 
invocations. 


Note that the bypass starting invocation modifier in operand 3 affects how the starting invocation is 
treated. If this modifier is false, then the starting invocation is the first invocation examined. If 
invocation range is zero in this case then only the starting invocation is examined. If, on the other 
hand, bypass starting invocation is true, then the starting invocation does not participate in the 
search, and, if invocation range is zero, no invocations are searched and a value of zero is 
returned for operand 1. 


Starting invocation pointer 
An invocation pointer to an invocation. If null, then the current invocation is indicated. If not null, 
then operand 2 must be 16-byte aligned in the space. 


If the pointer identifies an invocation in another process, a process object access invalid (hex 2C11) 2) 
exception will be signaled. If the invocation identified by this pointer does not exist in the stack, an 
object destroyed (hex 2202) exception will be signaled. 
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Usage note: 


Find Relative Invocation Number (FNDRINVN) 


In cases where starting invocation pointer is null, operand 2 may be a constant. 


Operand 3: The search criterion template identified by operand 3 must be aligned on a 16-byte 
boundary. The template is a 32-byte value with the following format: 


e Reserved (binary 0) 
e Search option 


¢ Search modifiers 


e Search argument 


Bypass starting invocation 


Char(8) 
Bin(4) 
Char(4) 
Bit 0 


O = The starting invocation identified by operand 2 is the first invocation tested. A invocation 
not found (hex 1E02) exception is signaled if the search criterion is not satisfied. 
1 = The starting invocation identified by operand 2 is skipped and no exception is signaled if 
the search criterion is not satisfied. 


Compare for mismatch 


Bit 1 


= The instruction identifies the first invocation (in specified search order) which matches the 
specified search criterion 


1 = The instruction identifies the first invocation (in specified search order) which does not 


match the specified search criterion 


Reserved (binary QO) 


Search option 
Specifies the invocation attribute to be examined: 


1 


Bit 1 
Char(16) 


Routine type. Search argument is a one-byte routine type, left aligned. Allowed search argu- 
ment values are: 


Hex 01 
Hex 02 
Hex 03 


OPM Program 
NPM Program Entry Procedure (PEP) 
NPM Procedure 


Invocation type. Search argument is a one-byte invocation type, left aligned. Allowed search 
argument values are: 


Hex 01 
Hex 02 
Hex 03 
Hex 04 
Hex 05 
Hex 06 
Hex 07 
Hex 08 
Hex 09 
Hex 0A 
Hex OB 
Hex OC 
Hex OD 
Hex OE 


Cail external 

Transfer control 

Event handler 

External exception handler (for OPM program) 
Initial program in process problem state 
Initial program in process initiation state 
Initial program in process termination state 
Invocation exit (for OPM program) 

Return or return/XCTL trap handler 

Call program 

Cancel handler (NPM only) 

Exception handler (NPM only) 

Call bound procedure/call with procedure pointer 


Process Default Exception Handler 
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Find Relative Invocation Number (FNDRINVN) 


3 Invocation status. Search argument consists of two four-byte fields, left aligned. The invoca- 
tion status of each examined invocation is ANDed with the first field and then compared to the 
second field. 


4 Invocation mark. Search argument is a four-byte invocation mark, left aligned. If the search is 
in the direction of older invocations, the result identifies the first invocation found with an invo- 
cation mark less than or equal to the search argument. If the search is in the direction of 
newer invocations, the result identifies the first invocation found with an invocation mark 
greater than or equal to the search argument. If invocation range is zero, then the search is 
satisfied only if the invocation mark of the starting invocation exactly matches the search argu- 
ment, and this can occur only if bypass starting invocation is false. 


For this option compare for mismatch is ignored. 


5 Activation mark. Search argument is a four-byte activation mark, left aligned. The activation 
mark of the program or module activation corresponding to each examined invocation is com- 
pared to search argument. Invocations with no activation (ie, the invocations of OPM reentrant 
programs, and the invocation stack base entry) are considered to have an activation mark of 
binary zero. 


6 Activation group mark. Search argument is a four-byte activation group mark, left aligned. 
The activation group mark of each examined invocation is compared to search argument. 


7 Program pointer. Search argument is a system pointer to a program. The program corre- 
spanding to each examined invocation is compared to the program identified by the pointer. 


Bypass starting invocation 
If bypass starting invocation is false, then the starting invocation specified by operand 2 is the first 
invocation examined. In this case, if the invocation range of operand 2 is exhausted without satis- 
fying the search criterion then a template value invalid (hex 3801) exception is signaled, with the 
search argument field of operand 3 identified as the erroneous field. 


lf bypass starting invocation is true, then the starting invocation specified by operand 2 is skipped, 
and a failure to satisfy the search criterion is indicated by returning a binary zero value in operand 
1. 


Compare for mismatch 
lf compare for mismatch is false, then the search criterion is satisfied when an invocation is found 
whose attribute matches the search argument. 
If compare for mismatch is true, however, then the search criterion is satisfied when an invocation 
is found whose attribute does not match the search argument. 


Search argument 
A value of between one and 16 bytes as described above. Unused bytes are ignored. 


Authorization Required: None 


Lock Enforcement: None 


Exceptions 
Operands 
Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation X X Xx 
02 boundary alignment X X 
03 range X X Xx 
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Exception 


08 


10 


16 


1C 


20 


22 


24 


2C 


2E 


32 


36 


38 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Exception management 


03 invalid invocation addrsss 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine observation 


02 invocation not found 


Machine support 
02 machine check 


03 function check 


Object access 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


11 Process object access invalid 


Find Relative Invocation Number (FNDRINVN) 


1A Invocation offset outside range of current stack 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 
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Operands 
1 2 3 Other 
X xX X 
X X X 
X 
X 
X 
X 
X 
X 
X 
X X X 
X X X 
X 
X X X 
X X X 
X 
X 
X 
X 
X 
X 
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Materialize Instruction Attributes (MATINAT) 


Materialize Instruction Attributes (MATINAT) 


Op Code (Hex) Operand 1 Operand 2 
0526 Receiver Selection informa- 
tion 


Operand 1: Space pointer. 


Operand 2: Character scalar (fixed length). 


Description: This instruction materializes the attributes of the instruction that are selected in operand 


2 and places them in the receiver (operand 1‘). 


Operand 2 is a 16-byte template. Only the first 16 bytes are used. Any excess bytes are ignored. 


Operand 2 has the following format: 
e Selection template 
— Invocation number 
— Instruction number 


— Reserved (binary 0) 


Char(16) 
Bin(2) 
Bin(4) 
Char(10) 


The invocation number is a specific identifier for the target invocation, in the process, that is to be 
materialized. This program must be observable or the program not observable (hex 1E01) exception is 


signaled. 


The instruction number specifies the instruction in the specified program invocation that is to be mate- 


rialized. 


2 


Operand 1 is a space pointer that addresses a 16-byte aligned template where the materialized data is 


placed. The format of the data is as follows: 
e Materialization size specification 


— Number of bytes provided by 
the user 


— Number of bytes available to be 
materialization 


¢« Object identification 

— Program type 

— Program subtype 

— Program name 
e Offset to instruction attributes 
e Reserved (binary 0) 
« instruction attributes 

— Instruction type 

- Instruction version 


Hex 0000 = 2-byte operand references 
Hex 0001 = 3-byte operand references 


- Reserved (binary 0) 


— Instruction length as input 
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Char(8) 
Bin(4) 


Bin(4) 


Char(32) 
Char(1) 
Char(1) 
Char(30) 
Bin(4) 
Char(8) 
Char(*) 
Char(2) 
Bits 0-3 


Bits 4-15 2 
Bin(2) 
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Materialize Instruction Attributes (MATINAT) 


to Create Program 


— Offset to instruction form specified Bin(4) 
as input to Create Program 
— Reserved (binary 0) Char(4) 
— Number of instruction operands Bin(2) 
— Operand attributes offsets Char(*) 
- An offset is materialized for each of the Bin(4) 
the operands of the instruction specifying the offset to the attributes for the operand 
— Instruction form specified as input Char(*) 
to Create Program 
- Instruction operation code Char(2) 
- Optional extender field and operand fields Char(*) 
— Operand attributes Char(*) 


A set of attributes following this format is materialized for each of the operands of the instruc- 
tion. Compound operand references result in materialization of only one set of attributes for 
the operand which describe the substring or array element as is appropriate. See the specific 
format described below for each operand type. 


- Operand type Bin(2) 
1 = Data object 
2 = Constant data object 
3 = Instruction number reference 
4 = Argument list 
5 = Exception description 
6 = Null operand 
7 = Space pointer machine object 
- Operand specific attributes Char(*) 
See descriptions below for detailed formats. Nothing is provided for null operands. 
« Data object Char(32) 
For a data object, the following operand attributes are materialized. 
— Operand type = 1 Bin(2) 
— Data object specific attributes Char(7) 
- Element type Char(1) 


Hex 00 = Binary 

Hex 01 = Floating-point 
Hex 02 = Zoned decimal 
Hex 03 = Packed decimal 
Hex 04 = Character 

Hex 08 = Pointer 


- Element length Char(2) 
e If binary, or character, or floating-point: 
— Length Bits 0-15 
e If zoned decimal or packed decimal: 
— Fractional digits Bits 0-7 
— Total digits Bits 8-15 
e If pointer: 


Chapter 21. Machine Observation Instructions 21-9 


— Length = 16 
e Array size 


— lf scalar, then value of 0. 


— If array, then number of elements. 


- Reserved (binary 0) 
- Data object addressability 


e Addressability indicator 


Hex 00 = Addressability was not established 


Hex 01 = 


Addressability was established 


e Space pointer to the object if 


addressability could be established 


e Constant data object 


Materialize Instruction Attributes (MATINAT) 


Bits 0-15 
Bin(4) 


Char(6) 
Char(17) 


Char(1) 


Space pointer 


Char(*) 


For a constant data object, the following operand attributes are materialized (immediate operands 
as constants, signed immediates as binary, and unsigned immediates as character). 


— Operand type = 2 
— Constant specific attributes 


- Element type 
Hex 00 = Binary 
Hex 01 = Floating-point 
Hex 02 = Zoned decimal 
Hex 03 = Packed decimal 
Hex 04 = Character 

- Element length 


e |f binary, or character, or floating-point: 


— Length 


« If zoned decimal or packed decimal: 


— Fractional digits 
— Total digits 


e Reserved (binary 0) 


- Reserved (binary 0) 
- Constant value 


e Instruction references 


Bin(2) 
Char(7) 
Char(‘) 


Char(2) -) 


Bits 0-15 


Bits 0-7 
Bits 8-15 


Bin(4) 


Char(7) 
Char(*) 


Char(*) 


For instruction references, either through instruction definition lists or immediate operands, the fol- 


lowing operand attributes are materialized. 


— Operand type = 3 Bin(2) 
— Number of instruction reference elements Bin(2) 
1 = Single instruction reference 
>1 = Instruction definition list 
— Reserved (binary 0) Char(12) 
— Reference list Char(*) 
The instruction number of each instruction reference is materialized in the order in which they a 
are defined. 
e Argument list Char(*) 
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Materialize Instruction Attributes (MATINAT) 


For an argument list, the following operand attributes are materialized. 


— Operand type = 4 Bin(2) 
— Argument list specific attributes Char(4) 
- Actual number of list entries Bin(2) 
- Maximum number of list entries Bin(2) 
— Reserved (binary 0) Char(10) 
— Addressability to list entries Char(*) 
Space pointer to each list entry for the Space pointer 


number of actual list entries. A value of all zeros is materialized if addressability could not be 
established. 


Exception description Char(48) 

For an exception description, the following operand attributes are materialized. 

— QOperand type = 5 Bin(2) 

— Reserved (binary 0) Char(10 

— Control flags Char(2) 
- Exception handling action Bits 0-2 


000 = Ignore occurrence of exception and continue processing 


001 = Disabled exception description 
010 = Continue search for an exception description by resignaling the exception to the 
immediately preceding invocation 
100 = Defer handling 
101 = Pass control to the specified exception handler 
- Reserved (binary 0) Bits 3-15 
— Compare value length Bin(2) 
— Compare value Char(32) 
Space pointer machine object Char(32) 


For a space pointer machine object, the following operand attributes are materialized. 


— Operand type = 7 Bin(2) 

— Reserved (binary 0) Char(13) 

— Pointer addressability Char(17) 
- Pointer value indicator Char(1) 


Hex 00= Addressability value is not valid 
Hex 01= Addressability value is valid 


— Space pointer data object containing the Space pointer 
Space pointer machine object value if addressability value is valid. 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the mateialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then excess bytes are unchanged. 
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The materialization available for an instruction depends on the execution status of the program that the 
instruction is in. If the program has not executed to the point of the instruction, little or no meaningful 
information about the‘instruction can be materialized. If the program executes the instruction multiple » 
times, the materialization will vary with each execution. 


No exceptions are signaled in the event that the receiver contains insufficient area for the 
materialization, other than the materialization length (hex 3803) exception described previously. 


This instruction is valid only when the program to be materialized is an OPM program. If the invoca- 
tion indicated by operand 2 is an invocation of an NPM program or procedure, then an instruction not 
valid for invocation type (hex 2C1C) exception is signaled. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

06 Optimized addressability invalid 


x KK XK 
x KX K MK 


08 Argument/Parameter 


01 Parameter reference violation 4 x 


10 Damage Encountered 
04 System object damage state X | ) 


44 Partial system object damage X 


1C Machine-Dependent Exception 


03 Machine storage limit exceeded X 


1E Machine Observation 


01 Program not observable X 


20 Machine Support 
02 Machine check Xx 
03 Function check X 


22 Object Access 
01 Object not found X 
02 Object destroyed X 
03 Object suspended X X 


08 object compressed X 


x< 


24 Pointer Specification 
01 Pointer does not exist X X 
02 Pointer type invalid X X 


2C Program Execution | 
1C Instruction not valid for invocation type X 2 | 


2E Resource Control Limit 
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Exception 


32 


36 


38 


01 User Profile storage limit exceeded 


Scalar Specification 
01 Scalar type invalid 
02 Scalar attributes invalid 


03 Scalar value invalid 


Space Management 


01 Space Extension/Truncation 


Template Specification 
01 Template value invalid 


03 Materialization length exception 


Materialize Instruction Attributes (MATINAT) 


Operands 
1 2 Other 
X 
X X 
X X 
X X 
X 
X 
X 
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Materialize Invocation (MATINV) 


Op Code (Hex) Operand 1 Operand 2 J 
0516 Receiver Selection informa- 
tion 


Operand ?/: Space pointer. 


Operand 2: Space pointer. 


ILE access 


MATINV ( 
receiver : space pointer; 
selection information : space pointer 


Description: The attributes of the invocation selected through operand 2 are materialized into the 
receiver designated by operand 1. 


Operand 2 is a space pointer that addresses a template that has the following format: 


¢ Control information Char(2) 
— Template extension Bit 0” 
0 = Template extension is not present. , 
1 = Template extension is present. ‘2 
— Invocation number Bits 1-15 
e Offset to list of parameters Bin(4)* 
e Number of parameter ODV numbers Char(2)* 
e Offset to list of exception descriptions Bin(4)* 
e Number of exception description Char(2) 
ODV numbers* 
e Template extension (optional) Char(14)* 
— Offset to list of space pointer Bin(4) 
machine objects* 
— Number of space pointer machine object Char(2) 
ODV numbers” 
— Reserved (binary 0) Char(8) 


Note: Fields annotated with an (*) must be set to ail binary zeroes if the invocation is for a bound 
program. The template extension field must also be set to zero. A template value invalid (hex 
3801) exception is signaled if the invocation is a bound program invocation and the fields are 
not set to binarary zeroes. 


The offset to the list of space pointer machine objects, offset to the list of parameters, and the offset to 
the list of exception descriptions are relative to the start of the operand 2 template. Each list is an 


array of Char(2) ODV numbers. The number of space pointer machine object ODV numbers, number of , 
parameter ODV numbers, and the number of exception description ODV numbers define the sizes of the = 
arrays. 
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Materialize Invocation (MATINV) 


Operand 1 is a space pointer that addresses a 16-byte aligned template into which the materialized 
data is placed. The format of the data is: 


¢ Materialization size specification Char(8) 
— Number of bytes provided by the user Bin(4) 
— Number of bytes available for materialization Bin(4) 
e Object identification Char(32) 
— Program type Char(1) 
— Program subtype Char(1) 
— Program name Char(30) 
e Trace specification Char(2) 
— Invocation trace status Bit O 
0 = Not tracing new invocations 
1 = Tracing new invocations 
— Return trace Bit 1 
0 = Not tracing returns 
1 = Tracing returns 
— Invocation trace propagation Bit 2 
0 = Not propagating invocation trace 
1 = Propagating invocation trace 
— Return trace propagation Bit 3 
0 = Not propagating return trace 
1 = Propagating return trace 
— Reserved (binary 0) Bits 4-15 
The following fields are returned only for non-bound program invocations. 
e Instruction number UBin(2) 
e Offset to parameter values Bin(4) 
e Offset to exception description value Bin(4) 
e Offset to space pointer machine object values Bin(4) 
(Optional-This data is present only if the template extension is present in the selection information.) 
e Space pointer machine objects Char(*) 


(Optional-This data is present only if the template extension is present in the selection information.) 


— For each ODV number specified for a Char(32) 
space pointer machine object, the value of the space pointer machine object is materialized as 


follows: 
- Reserved (binary 0) Char(15) 
- Pointer value indicator Char(1) 


00 = Addressability value is not valid 
01 = Addressability value is valid 


- Space pointer data object containing Space pointer 
the space pointer machine object value if addressability value is valid. 


Char(*) 


Space pointer 


¢ Parameters 


— For each parameter ODT number specified, 
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Materialize Invocation (MATINV) 


the address of the parameter data is materialized (If no parameter ODT numbers are material- 
ized, this parameter is binary 0.) 


e Exception description Char(*) 
— For each exception description ODT number Char(36) 
specified, the following is materialized: 
— Control flags Char(2) 
- Exception handling action Bits 0-2 


000 = Ignore occurrence of exception and continue processing 

001 = Disabled exception description 

010 = Continue search for an exception description by resignaling the exception to the 
immediately preceding invocation 

100 = Defer handling 

101 = Pass control to the specified exception handler 


- Reserved (binary 0) Bits 3-15 
— Compare value length Bin(2) 
— Compare value Char(32) 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, then excess bytes are unchanged. 


No exceptions (other than the materialization length (hex 3803) exception) are signaled in the event 
that the receiver contains insufficient area for the materialization. 

The instruction number returned depends on how control was passed from the invocation: 

Exit Type Instruction Number 

Call External Locates the Call External instruction 

Event Locates the next instruction to execute 

Exception Locates the instruction that caused the exception 

The space pointers that address parameter values are returned in the same order as the corre- 


sponding ODT numbers in the input array. The same is true for the exception description values. 


If the offset to the list of parameters or the number of parameter ODT numbers is 0, no parameters are 
returned and the offset to parameters value is 0. If any parameters are returned, they are 16-byte 
aligned. If the offset to list of exception descriptions or the number of exception description ODT 
numbers is 0, no exception descriptions are returned and the offset to exception description values are 
0. - 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation X X 
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Exception 


08 


1C 


1E 


20 


22 


24 


2E 


32 


36 


38 


02 boundary alignment 
03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine observation 


01 program not observable 


Machine support 
02 machine check 


03 function check 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 


02 scalar attributes invalid 


Space management 


01 space extension/truncation 


Template specification 
01 template value invalid 


03 materialization length exception 


Materialize Invocation (MATINV) 


Operands 
1 2 Other 
X X 
X X 
X X 
X X 
X X X 
X X X 
X 
X 
X 
X 
X 
X X 
X X 
X 
X X 
X X 
X 
X X 
X X 
X 
X 
X 
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Materialize Invocation Attributes (MATINVAT) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0533 Receiver Invocation identifi- Attribute selection 
cation template 


Operand 1: Space pointer. 
Operand 2: Character(48) scalar (fixed length) or null. 


Operand 3: Space pointer. 


ILE access 
MATINVAT ( 
receiver : Space pointer 
var invocation identification : aggregate; OR 


null operand; 
attribute selection template : space pointer 


Description: The attributes specified by operand 3 of the invocation specified by operand 2 are materi- 
alized into the receiver specified by operand 1. In addition to specifying the attributes to be material- 
ized, operand 3 controls how they are arranged in the operand 1 receiver. 


Operand 1 is a space pointer to an area that is to receive the materialized attribute values. The format 
of this area is determined by the value of the attribute selection template. 


Operand 2 identifies the source invocation whose attributes are to be materialized. It also identifies 
the originating invocation whose activation group access right to the source invocation’s activation 
group is to be verified. If operand 2 is null, the invocation issuing the instruction is both the source 
invocation and the originating invocation. 


Operand 3 is a space pointer to a template that selects the invocation attributes to be materialized and 
specifies how they are to be arranged in the receiver template. 


Operand 2 


The value specified by operand 2 identifies the source and originating invocations. This operand can 
be null (which indicates the current invocation is to be used for the source and originating invocations) 
or it can contain either a invocation pointer to an invocation or a null pointer (which indicates the 
current invocation). 


Operand 2 has the following format: 


¢ Source invocation offset Bin(4) 

¢ Originating invocation offset Bin(4) 

e Invocation range (ignored) Bin(4) 

e Reserved (binary 0) Char(4) 

e Source invocation pointer Invocation pointer 
e Reserved (binary 0) Char(16) 


If a non-null pointer is specified for source invocation pointer, then operand 2 must be 16-byte aligned 
in the space. 
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Terminology: 


Requesting invocation 
The invocation executing the MATINVAT instruction. Note that, in many cases, this invoca- 
tion belongs to a system or language run-time procedure/program, and the instruction is 
actually being executed on behalf of another procedure or program. 


Originating invocation 
The invocation on whose behalf the instruction is being executed. It may be necessary to 
identify this invocation since its “activation group access rights” may need to be checked. 
This allows, for example, the requesting invocation to be a system state invocation with the 
instruction still performing an “activation group access rights” check that reflects the rights 
of the user. 


Source invocation 
The invocation whose attributes are to be materialized. 


Activation group access rights 
The rights that invocations executing in one activation group may have to access and 
modify the resources of another activation group. 


Field descriptions: 


Source invocation offset 
A signed numerical vaiue indicating an invocation relative to the invocation located by the source 
invocation pointer. A value of zero denotes the invocation addressed by the source invocation 
pointer, with increasingly positive numbers denoting increasingly later invocations in the stack, and 
increasingly negative numbers denoting increasingly earlier invocations in the stack. 


If the source invocation pointer is not valid or the invocation identified by this offset does not exist 
in the stack, an invocation offset outside range of current stack (hex 2C1A) exception will be sig- 
naled. 


Originating invocation offset 
A signed numerical value identifying the originating invocation relative to the current invocation. 
Since this is an offset relative to the current invocation, only zero or negative values are allowed. 


If the invocation identified by this offset does not exist in the stack, an invocation offset outside 
range of current stack (hex 2C1A) exception will be signaled. 


Invocation range 
This field is used by FNDRINVN and is ignored by this instruction. 


Source invocation pointer 
An invocation pointer to an invocation. If null, then the current invocation is indicated. 


If the pointer identifies an invocation in another process, a process object access invalid (hex 2C11) 
exception will be signaled. If the invocation identified by this pointer does not exist in the stack, an 
object destroyed (hex 2202) exception will be signaled. 


Activation group access rights checking: This instruction sometimes (depending on the attributes 
materialized) requires that activation group access rights to the activation group of the source invoca- 
tion be verified. In such cases, the originator offset field of operand 2 identifies the invocation whose 
right of access is to be checked. (That is, it identifies the invocation which is considered to have origi- 
nated the request and on whose behalf the instruction is being executed.) 


If originator offset is not zero, then the activation group of the requesting invocation must have the 
right to access the activation group of the invocation identified by originator offset. This check is made 
whether or not access rights to the source invocation need to be checked. 
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In the event that appropriate access rights are not found, an activation group access violation (hex 
2C12) exception is signaled. 


Note: The originating invocation identified by the originating invocation offset must be equal to or 


Usage note: In cases where source invocation pointer is null, operand 2 may be a constant. 


Operand 3: The attribute selection template has the following format: 


¢ Selection template header Char(16) 
— Number of attributes Bin(4) 
— Control flags Char(‘) 
- Attribute index indirect Bit O 


O = Offset to attribute index specifies directly the location of the attribute index value 


“newer” than the invocation identified as the source invocation. Otherwise, an invalid origin 
invocation (hex 2C19) exception will be signaled. 


1 = Offset to attribute index specifies the location of a space pointer which in turn specifies 


the location of the attribute index value 


- Reserved (binary 0) Bits 1-7 
— Reserved (binary 0) Char(3) 
— Offset to attribute index Bin(4) 
— Length of attribute index Bin(4) 
e Attribute selection entries ‘Char(") 


The attribute selection entries are each 16 bytes long and have the following format: 


e Attribute ID Bin(4) 
¢ Control flags Char(1) 
— Indirect Bit 0 


O = Offset to receiver specifies directly the location of the attribute value 
1 = Offset to receiver specifies the location of a space pointer which in turn specifies the 
location of the attribute value 


Return length Bit 1 


0 = A length field is not present with the attribute 
1 = A length field precedes the attribute 


Return status Bit 2 


0 = A status field is not present with the attribute 
1 = A status field precedes the attribute 


Pad Bit 3 


0 = No pad field is assumed to precede the attribute 
1 = A pad field of zero, eight, or twelve bytes is assumed to precede the attribute 


— Reserved (binary 0) Bits 4-7 
e Reserved (binary 0) Char(3) 
e Offset to receiver Bin(4) 
e Length of receiver Bin(4) 
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Materialize Invocation Attributes (MATINVAT) 


Basic structure: The “attribute selection template” allows the user of MATINVAT considerable flexi- 
bility in deciding what invocation attributes are to be materialized and where their materializations are 
to be returned. This flexibility is achieved by having the “attribute selection template” consist of a 
header, followed by a series of entries, each of which identifies an attribute to be materialized, the 
location where it is to be materialized, and the amount of space reserved for its materialization. 


The template header specifies the number of attribute entries present in the template, and it also 
allows the specification of an optional attribute index field. The attribute index field, if present, identi- 
fies the first attribute selection entry to be processed (causing entries prior to that one to be skipped). 
In addition, if the attribute index field is present, it is updated upon the normal or abnormal completion 
of the instruction to contain either zero (if completion is normal) or the number of the entry being proc- 
essed (if the instruction ends with an exception). 


Each attribute selection entry identifies the attribute to be materialized and the area where the 
materialization is to be returned. The attribute may be returned directly into the area addressed by 
the operand 7 space pointer, or it may be returned into an area addressed by a space pointer which is, 
in turn, contained in the area addressed by the operand 7? space pointer. These two cases are distin- 
guished by the /ndirect bit. 


In addition, each attribute selection entry contains: 


e An offset value which is the offset relative to the operand 7 space pointer where either the attri- 
bute’s materialization area or the pointer to the attributes’ materialization area is contained. 


¢ A length value identifying the maximum number of bytes of data to be materialized for the attri- 
bute. 


¢ A flag indicating whether the length of the attribute is to be materialized. 
¢ A flag indicating whether the status of the attribute is to be materialized. 


e A flag indicating whether a pad field precedes the attribute (or its pointer, if indirect is specified). If 
present, the length of this “pad” field is automatically adjusted so that the combined length of the 
length, status, and pad fields is either zero or 16, maintaining the relative quadword alignment of 
the modification value if the length and/or status fields are present. 


Note that, for the sake of regularity, the fields of the attribute selection template header are arranged in 
the same general fashion as those in the attribute selection entries. 


Field descriptions: 


Number of attributes 
Specifies how many 16-byte attribute selection entries follow. 


Attribute index indirect 
lf attribute index indirect is binary zero, then offset to attribute index specifies the location where 
the attribute index is stored as as offset from the location addressed by the operand 7 space 
pointer. If attribute index indirect is binary one, then the location identified by attribute index offset 
must be quadword aligned and must contain a space pointer. This space pointer in turn addresses 
the location where the attribute index value is stored. 


Offset to attribute index 
Specifies the offset to the attribute index or the offset to a pointer to the attribute index, depending 


on the value of attribute index indirect. 


Length of attribute index 
Specifies the length of the area where the attribute index value is stored. This field must have a 


value of either zero or four. 
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If this field has a value of zero, then the first attribute entry to be processed is the first attribute 
entry in the template. and no feedback is given as to which attribute entry was being processed at 
the time of an exception. Attribute index indirect and attribute index offset are ignored. 


If this field has a value of four, then the value of the attribute index, treated as a signed bin(4) 
value, must be greater than or equal to one and less than or equal to number of attributes. |n this 
case the attribute index identifies the attribute entry to be processed first (with the first entry in the 
template having an index of one), and, in the event of an exception, the attribute index value is 
modified by this instruction such that it identifies the attribute entry being processed at the time of 
the exception. If the instruction completes without an exception, then the attribute index value is 
set to zero. 


Attribute |D 
Specifies the attribute to be materialized. Values that may be specified are: 


1 
2 


Invocation pointer to specified invocation. (16 bytes, quadword aligned.) 


Automatic storage pointer. Space pointer to the automatic storage for this invocation. If no 
automatic storage exists for this invocation, then a null pointer is returned. (16 bytes, 
quadword aligned, access rights required.) 


Static storage pointer. Space pointer to the static storage for this invocation (OPM invocations 
only). If no static storage exists for this invocation, or if the invocation is an NPM invocation, 
then a null pointer is returned. (16 bytes, quadword aligned, access rights required.) 


Note: For NPM invocations there is no single “distinguished” static storage area, but instead 
there may be multiple static storage areas. The list of static storage areas corresponding to 
the invocation’s activation can be obtained by using the Materiailze Activation Attributes 
instruction. 


Parameter list pointer. Space pointer to the parameter list passed to this invocation (NPM 
procedure invocations only). If the procedure for this invocation does not expect a parameter 
list, or if this is an NPM entry routine or an OPM program, then a null pointer is returned. (16 
bytes, quadword aligned, access rights required.) 


Program pointer. System pointer to the program for this invocation. If the program no longer 
exists then a null pointer is returned. (16 bytes, quadword aligned, access rights required.) 


Space pointer to module associated space. For NPM procedures, this space pointer addresses 
the secondary associated space in the NPM program that was propagated from the primary 
associated space of the NPM module. For OPM programs, this space pointer addresses the 
program’s primary associated space. If the appropriate associated space does not exist in the 
program or if the program no longer exists, then a null pointer is returned. For both NPM and 
OPM invocations the requesting invocation must have space authority to the program. (16 
bytes, quadword aligned, access rights required.) 


Pointer to containing scope. If the specified invocation is in a nested scope, then this is an 
invocation pointer to the invocation of the containing scope. Otherwise a null pointer is 
returned. (16 bytes, quadword aligned.) 


Relative invocation offset to containing scope. If the specified invocation is in a nested scope, 
then this is the relative invocation offset to the invocation of the containing scope. Otherwise, 
a value of zero is returned. Note that the relative invocation offset will be a negative number 
and is relative to the specified invocation. (4 bytes.) 


Lexical level number. Outer procedures have a lexical level number of 1. (4 bytes.) 
Invocation number. (2 bytes.) 
Invocation mark. (4 bytes.) 


Activation mark. If no activation exists for this invocation, then a zero value is returned. (4 


bytes.) 
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14 Activation group mark. (4 bytes.) 


15 Invocation type. The possible values for invocation type are: 


16 


17 
18 
19 


Hex 01 
Hex 02 
Hex 03 
Hex 04 
Hex 05 
Hex 06 
Hex 07 
Hex 08 
Hex 09 
Hex 0A 
Hex OB 
Hex OC 
Hex 0D 
Hex OE 


Call external 

Transfer control 

Event handler 

External exception handler (for OPM program) 
Initial program in process problem state 
Initial program in process initiation state 
Initial program in process termination state 
Invocation exit (for OPM program) 

Return or return/XCTL trap handler 

Call program 

Cancel handler (NPM only) 

Exception handler (NPM only) 

Call bound procedure/call with procedure pointer 


Process Default Exception Handler 


(1 byte.) 


Routine type. The possible values for routine type are: 


Hex 01 
Hex 02 
Hex 03 


OPM Program 
NPM Program Entry Procedure (PEP) 
NPM Procedure 


(1 byte.) 


State invocation was invoked with. (2 bytes.) 


State for invocation. (2 bytes.) 


Invocation status of the specified invocation (including invocation flags). 


Bit 0 
Bit 1 


Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Bit 8 
Bit 9 
Bit 10 


Cancelled 


Ending -- a return operation has been initiated from within the invocation or the actual 
termination of a cancelled invocation has begun. 


Invocation interrupted by exception 

Invocation interrupted by event (reserved) 

Invocation is an OPM CALLX exception handler 
Invocation contains an OPM CALLI exception handler 
Invocation contains a signalled OPM branchpoint handler 
Retry not allowed 

Resume not allowed 

Resume point has been modified 


Invocation is a program entry procedure and is marked as the oldest in the activation 
group 


Bits 11-15 Reserved 
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23 
24 


25 


26 


27 


28 


29 


30 
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Bits 16-31 Invocation flags 


(4 bytes.) 

Performance consideration: When the only invocation status information required is the invo- J 
cation flags, there may be a significant performance advantage if the following attribute is 

materialized instead of this one. 


Invocation flags of the specified invocation. This attribute has the same format as the invoca- 
tion status attribute, except that the first two bytes are returned as zero. (4 bytes.) 


Cancel reason of the specified invocation. (4 bytes.) 


Suspend point. Suspend pointer identifying the location within the invocation’s routine where 
execution was suspended due to a call, interrupt, or machine operation. If the program no 
longer exists then a null pointer is returned. (16 bytes, quadword aligned, access rights 
required.) 


Resume point. 


A suspend pointer identifying the location within the invocation’s routine where execution will 
resume if execution is allowed to resume in the invocation. If the invocation is suspended for 
some cause that permits resumption, then this is initially set to the location that logically 
follows the suspend point. If the invocation is suspended for some cause that does not permit 
resumption, then this is initially set to be a null pointer. If the resume point is modified via 
Modify Invocation Attributes then a suspend pointer (or null pointer) corresponding to the mod- 
ified resume point is returned. If the program no longer exists or if the invocation is cancelled 
or ending, then a null pointer is returned. (16 bytes, access rights required, quadword 
aligned.) 


Interrupt message invocation. If the invocation is interrupted due to an exception interrupt, 

and the message causing the interrupt has not been removed or modified to a non-interrupt J 
state, then this is an invocation pointer which addresses the invocation to which the interrupt 

message is enqueued. If no interrupt cause currently exists, then a null pointer is returned. 

(16 bytes, quadword aligned.) 


Interrupt message reference key. If the invocation is interrupted due to an exception interrupt, 
and the message causing the interrupt has not been removed or modified to a non-interrupt 
state, then this is the message reference key of the interrupt cause message. If no interrupt 
cause currently exists, then a value of zero is returned. (4 bytes.) 


External exception handler’s monitoring invocation. If the specified invocation is an external 
exception handler for an OPM program, then this is an invocation pointer identifying the invo- 
cation which enabled the handler (also the invocation where the exception message is cur- 
rently enqueued). Otherwise, a null pointer is returned. (16 bytes, quadword aligned.) 


External exception handler’s message reference key. If the specified invocation is an external 
exception handler for an OPM program, then this is the message reference key of the corre- 
sponding exception message. Otherwise, a zero value is returned. (4 bytes.) 


OPM internal exception handler’s message reference key. If the specified invocation is an 
OPM invocation with an internal exception handler active, then this is the message reference 
key of the exception message corresponding to the currently active internal exception handler. 
Otherwise, a zero value is returned. (4 bytes.) 


OPM branchpoint exception handler’s message reference key. If the specified invocation is an 
OPM invocation with a branchpoint exception handler in a signalled state, then this is the 
message reference key of the exception message corresponding to the most recently signalled 
branchpoint exception exception handler. Otherwise, a zero value is returned. (4 bytes.) 
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32 Trap handler’s message reference key. If the specified invocation was invoked as a trap 
handler, then this is the message reference key of the corresponding trap message. (Note that 
the trapped invocation is. by definition, the immediately preceding invocation.) Otherwise. a 
zero value is returned. (4 bytes.) 


Where “access rights required” is specified above, the activation group of the invocation identified 
as the originating invocation must have activation group access rights to the activation group of the 
source invocation or else an activation group access violation (hex 2C12) exception is signaled. 


The invocation with an invocation number of 1 is always the first invocation in the stack. 


Indirect 


If indirect is binary zero, then offset to receiver specifies the location where the selected attribute 
value is to be materialized as as offset from the location addressed by operand 1. If indirect is 
binary one, then the location identified by offset to receiver, after accounting for any length, status, 
or pad fields specified, must be quadword aligned and must contain a space pointer. This space 
pointer in turn addresses the location where the selected attribute value is to be materialized. 


Return length 


If return length and return status are both binary zero, then only the attribute itself is materialized. 
If return length is binary one, then the attribute (or attribute pointer, if indirect is true) is preceded 
by a four-byte value which specifies the length of the attribute (exclusive of the length value itself, 
and the status and pad fields, if present). 


Return status 


lf return status is binary one, then the attribute (or attribute pointer, if inGirect is true) is preceded 
by a four-byte value which contains the status of the attribute. 


If the status value is returned, it has the following format: 


Bits 0-2 Reserved (binary 0) 


Bit3 Attribute unavailable at this time. (Eg, asking for the system pointer to a destroyed OPM 
program.) The result returned is zeros for the minimum length defined. 


Bit 4 Attribute not defined in this context. (Eg, asking for lexical level number from OPM invoca- 
tion.) The result returned is zeros for the minimum length defined. 


Bit5 Attribute not defined at this time. (Eg, asking for interrupt message invocation when the 
invocation is not interrupted.) The result returned is zeros for the minimum length defined. 


Bit6 Attribute defined but null. (Eg, when asking for the resume point for an invocation for which 
resume is not currently allowed.) The result returned is zeros for the minimum length 
defined. 


Bit 7 Attribute truncated. Indicates that the specified /ength of receiver was too small to allow 
the entire attribute to be returned. The truncated result is returned, as described earlier. 


Bits 8-31 Reserved (binary 0) 


If return length and return status are both binary one then the length field comes first, followed 
immediately by the status field. 


If either return length or return status is binary one, and pad is also binary one, then twelve bytes 
of pad are assumed between the length or status value and the attribute (or attribute pointer, if 
indirect is true). If both return Jength and return status are binary one, and pad is also binary one, 
then eight bytes of pad are assumed between the status value and the attribute (or attribute 
pointer). If return length and return status are both binary zero, then no padding occurs, regard- 
less of the value of pad. The area occupied by the pad is not modified by this instruction. 
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Note: Pad makes it easier to quadword align the area to receive the materialized attribute (if indi- 
rect is false) or the area containing the attribute pointer (if indirect is true) when return status 
and/or return /ength are also specified. 


Offset to receiver 
Specifies the offset to the location where the selected attribute value is to be materialized, or the 
offset to a pointer to the location, depending on the value of indirect. 


Length of receiver 
Specifies the length of the area where the attribute value is to be materialized. 


This length indicates the length of the actual area available for materializing the attribute, and does 
not include the length of any length, status, or pad field. If the number of bytes of attribute data 
available to be materialized (exclusive of the status, length, and pad fields, if any) exceeds /ength 
of receiver, then only /ength of receiver bytes of data are returned. No exception is signalled in 
this case. 


If indirect is a binary zero, then /ength of receiver indicates the length of the area located by offset 
to receiver. If indirect is a binary one, then /ength of receiver indicates the length of the area 
located by the indirect space pointer identified by offset to receiver. 


In the case that /ength of receiver is sufficient to receive only part of a field in an attribute struc- 
ture, then the partial field may or may not be materialized. 


Individual attribute entries are processed in order, with the attributes specified by each entry being 
materialized before processing of the next entry begins. If an exception occurs while processing an 
attribute entry, then the attributes materialized due to the preceding attribute:entries will still be 
present in their specified result locations. 


For attributes which include pointers, the specified direct or indirect value location, after accounting for 
any length, status, or pad fields, must be quadword aligned or a boundary alignment (hex 0602) excep- 
tion may occur. (The exception is not guaranteed to occur, eg, in the case where /ength of receiver is 
insufficient to include the materialized pointer, or when a null pointer is returned.) 


If the value locations of individual attribute entries overlap, then the values will be overlaid in the 
sequence implied by the attribute entry order. |f the value location of a non-indirect result overlays the 
location of the space pointer for an indirect result, then the validity of the space pointer will depend on 
the order of the associated entries. 


Authorization Required 
e Activation group access 


— From the activation group of the invocation issuing the instruction to the activation group of the 
originating invocation identified by operand 2 


— When an attribute annotated with “access rights required” is specified: From the activation 
group of the originating invocation identified by operand 2 to the activation group of the source 
invocation identified by operand 2 


e Space authority 
— For the module associated space option, the requesting invocation must have space authority 
to the program executing in the source invocation identified by operand 2 


Lock Enforcement: None 


Exceptions 
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06 


08 


0A 


10 


1c 


20 


22 


24 


2C 


2E 


32 


36 


38 


Addressing 

01 space addressing violation 
02 boundary alignment 

03 range 


06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Authorization 


01 Unauthorized for operation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 
03 function check 


Object access 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Program execution 


11 Process object access invalid 


12 Activation group access violation 


19 Invalid origin invocation 
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1A Invocation offset outside range of current stack 


Resource control! limit 


01 user profile storage limit exceeded 


Scalar specification 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 


01 template value invalid 
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Materialize Invocation Entry (MATINVE) 


Op Code (Hex) Operand 1 Operand 2 Operand 3 
0547 Receiver Selection informa- Materialization 
tion options 


Operand ?: Character variable scalar (fixed length) 
Operand 2: Character(8) scalar (fixed length) or null. 
Operand 3: Character(1) scalar (fixed length) or null. 


Description: This instruction materializes the attributes of the specified invocation entry within the 
process issuing the instruction. The attributes specified by operand 3 of the invocation selected 
through operand 2 are materialized into the receiver designated by operand 1. 


Operand 2 is an 8-byte template or a null operand. If.operand 2 is null, it indicates that the attributes 
of the current invocation are to be materialized. If operand 2 is not null, it must be an 8-byte template 
which specifies the invocation to be materialized. Only the first 8 bytes are used. Any excess bytes 
are ignored. It has the following format: 


e Selection information Char(8) 
— Relative invocation number Char(2) 
— Reserved ‘Char(6) 


If operand 2 is not null, it is restricted to a constant with the relative invocation number field specifying 
a value of zero, which indicates that the attributes of the current invocation are to be materialized. 


Operand 3 is a 1-byte value or a null operand. If operand 3 is null, it indicates that the attributes for a 
materialization option value of hex 00 are to be materialized. If operand 3 is not null, it must be a 
1-byte value which specifies the type of materialization to be performed. Option values that are not 
defined below are reserved values and may not be specified. Only the first byte is used. Any excess 
bytes are ignored. It has the following format: 


¢ Materialization options Char(1) 


Hex 00 = Long materialization 

Hex 01 = Short materialization type 1 
Hex 02 = Short materialization type 2 
Hex 03 = Short materialization type 3 
Hex 04 = Short materialization type 4 
Hex 05 = Short materialization type 5 


If operand 3 is not null, it is restricted to a constant character scalar or an immediate value. 


Operand 1 specifies a receiver into which the materialized data is placed. It must specify a character 
scalar with a minimum length which is dependent upon the materialization option specified for operand 
3. If the length specified for operand 1 is less than the required minimum, an exception is signaled. 
Only the bytes up to the required minimum length are used. Any excess bytes are ignored. For the 
materialization options which produce pointers in the materialized data, 16-byte space alignment is 
required for the receiver. The data placed into the receiver differs depending upon the materialization 
option specified. The following descriptions detail the formats of the optional materializations. 
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Long Materialization: For a materialization option value of hex 00. the minimum length for the receiver 
is 144 bytes. It has the following format: 


= * Hex 00 = Long materialization Char(144) 
— Reserved Char(12) 
— Mark counter Bin(4) 
— Reserved Char(32) 
— Associated program pointer System pointer 
(zero for data base select/omit program) 
— Invocation number Bin(2) 
— Invocation type Char(1) 


Hex 00= Data base select/omit program 

Hex 01 = Call external 

Hex 02 = Transfer control 

Hex 03 = Event handler 

Hex 04 = External exception handler 

Hex 05 = Initial program in process problem state 
Hex 06 = Initial program in process initiation state 
Hex 07 = Initial program in process termination state 
Hex 08 = Invocation exit 

Hex 09 = Return trap handler or return/XCTL trap handler 
Hex OA = Call program 

Hex OB = Reserved 

Hex OC = Reserved 

Hex OD = Reserved 

Hex OE = Process Default Exception Handler 


— Reserved (binary 0) Char(1) 

— Invocation mark Bin(4) 

— State invocation was invoked with Char(2) 

— State for invocation Char(2) 

— Reserved Char(4) 
| — Automatic storage frame (ASF) pointer Space pointer 
| — $Static storage frame (SSF) pointer Space pointer 

— Reserved Char(32) 


Short Materialization Type 1: For a materialization option value of hex 01, the minimum length for the 
receiver is 16 bytes. It has the following format: 


Hex 01 = Short materialization type 1 Char(16) 
« Associated program pointer System pointer 
(null for data base select/omit program) 
Short Materialization Type 2: For a materialization option value of hex 02, the minimum length for the 
receiver is 4 bytes. It has the following format: 
Hex 02 = Short materialization type 2 Char(4) 
C ¢ Invocation mark Bin(4) 
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Short Materialization Type 3: For a materialization option value of hex 03, the minimum length for the 
receiver is 16 bytes. It has the following format: 


Hex 03 = Short materialization type 3 Char(16) J 
¢ ASF pointer Space pointer 
Short Materialization Type 4: Fora materialization option value of hex 04, the minimum length for the 
receiver is 16 bytes. It has the following format: 
Hex 04 = Short materialization type 4 Char(16) 
¢« SSF pointer Space pointer 


Short Materialization Type 5: For a materialization option value of hex 05, the minimum length for the 
receiver is 4 bytes. It has the following format: 


Hex 05 = Short materialization type 5 Char(4) 
e State invocation was invoked with Char(2) 
° State for invocation Char(2) 


The mark counter value represents the current value of a counter used by the machine to mark all 

activations and a subset of the invocations created during the execution of a process with a unique 

value. This mark indicates the point at which the specific entry was allocated relative to the sequence 

of all activations and invocations that have been created over time within the process. That is, older 
activations will be identified by a mark value of lesser value, and newer activations and invocations will 

be identified by a mark value.of higher value. The mark counter is just the highest number assigned so 

far as a unique id. It does not act as a counter of how many activations and invocations have been 

created in the process. This is because invocations are assigned a mark value only as needed by the 

machine to ensure the visible function of the mark count. That is, any invocation mark value which is ' 
supplied to the user of the machine does indeed uniquely identify the invocation and indicate its cre- 2 
ation sequence relative to the activations and invocations currently existing in the process, but it is not 

an absolute counter. 


The associated program pointer is a system pointer that locates the program associated with the invo- 
cation entry. 


The invocation number is the stack depth of the invocation within the invocation stack. The invocation 
number of a new invocation entry is one more than that in the calling invocation. The first invocation 
in the current process has an invocation number of one. 


The invocation type indicates how the associated program was invoked. 


The invocation mark captures the current mark counter value to uniquely identify the invocation within 
the process. An activation implicitly created on behalf of the invocation will be identified by a mark 
value of equal value. 


The state invocation was invoked with value represents the state in which the machine was running 
when the program was called or transfered to. 


State for invocation value represents the state in which the machine is running the program. 


The ASF pointer is a space pointer that is set to address the start of the ASF. associated with the 
invocation. The associated program’s automatic data starts 64 bytes after the area addressed by this 
pointer. 


wa 


The SSF pointer is a space pointer that is set to address the start of the SSF (static storage frame) 
associated with the invocation. The associated program’s static data starts 64 bytes after the area 
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addressed by this pointer. This pointer will be set to a value of all zeros if the invoked program does 
not have static data. 


The fields labeled reserved in the descriptions of the optional materializations are currently reserved 
for future use. These fields may be altered by this instruction depending upon the particular imple- 
mentation of the machine. Any values set into these fields are meaningless. 


Exceptions 


Exception 


06 


08 


1c 


20 


22 


24 


2E 


32 


36 


Addressing 

01 space addressing violation 

02 boundary alignment 

03 range 

06 optimized addressability invalid 


Argument/parameter 


01 parameter reference violation 


Damage encountered 
04 system object damage state 


44 partial system object damage 


Machine-dependent exception 


03 machine storage limit exceeded 


Machine support 
02 machine check 


03 function check 


Object access 

01 abject not found 
02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 
02 scalar attributes invalid 


03 scalar value invalid 


Space management 


01 space extension/truncation 
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Op Code (Hex) Operand 1 Operand 2 
0546 Receiver Process 


Operand 7: Space pointer. 


Operand 2: System pointer or null. 


ILE access 


MATINVS ( 
receiver : space pointer; 
var process : system pointer OR 
null operand 


Description: This instruction materializes the current invocation stack within the specified process. 


The attributes of the invocation entries currently on the invocation stack of the process specified by 
operand 2 are materialized into the template specified by operand 1. 


Operand 2 is a system pointer or a null operand. If operand 2 is null, it indicates that the invocation 
stack of the current process is to be materialized. If operand 2 is not nuil, it is a system pointer identi- 
fying the process control space associated with the process for which the invocation stack is to be 
materialized. If the subject process, identified by operand 2, is different from the process executing 
this instruction, the executing process must be the original initiator of the subject process or must have 
process control special authorization to the process control space associated with the subject process. 


Operand 1 is a space pointer that addresses a 16-byte aligned template into which is placed the mate- 
rialized data. The format of the data is: 


e Materialization size specification Char(8) 
— Number of bytes provided by the user Bin(4) 
— Number of bytes available for materialization Bin(4) 
¢ Number of invocation entries Bin(4) 
¢ Mark counter Bin(4)* 
¢ Invocation entries Char(*) 


{An invocation entry is materialized for each of the invocations currently on the invocation stack of 
the specified process.) 


The invocation entries materialized are each 128 bytes long and have the following format: 


e Reserved Char(32) 

e Associated program pointer System pointer 
(null for data base select/omit program or a destroyed program) 

e Invocation number Bin(2) 

e Invocation mechanism Char(1) 


Hex 01 Call external 


Hex 02 Transfer control 
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Hex 03 Event handler 
Hex 04 External exception handler (for OPM program) 
Hex 05 Initial program in process problem state 
Hex 06 Initial program in process initiation state 
Hex 07 Initial program in process termination state 
Hex 08 Invocation exit (for OPM program) 
Hex 09 Return or return/XCTL trap handler 
Hex OA Call program 
Hex OB Cancel handler (NPM only) 
Hex OC Exception handler (NPM only) 
Hex 0D Call bound procedure/call with procedure pointer 
Hex OE Process Default Exception Handler 
e Invocation type Char(1) 
Hex 01 OPM Program 
Hex 02 NPM Program Entry Procedure (PEP) 
Hex 03 NPM Procedure 


e Invocation mark _ Bin(4)* 

¢ Instruction identifier Bin(4) 
(zero for data base select/omit program, destroyed, damaged, or suspended program) 

¢ Activation group mark Bin(4) 

e Suspend point Suspend pointer 
(null for data base select/omit program or destroyed program) 

e Reserved Char(48) 


Note: Values annotated with an asterisk (*) may not be materialized if operand 2 identifies a process 
other than the one executing this instruction. Unmaterialized fields are set to binary zeros. 


Values annotated with a double asterisk (**) are materialized only if operand 2 is null or identi- 
fies the process executing this instruction, and the program executing this instruction is in 
system state. Unmaterialized fields are set to binary zeros. 


The number of invocations value specifies the number of invocation entries provided in the 
materialization. 


The mark counter value represents the current value of a counter used by the machine to mark all 
activations and invocations created during the execution of a process with a unique value. This mark 
indicates the point at which the specific entry was allocated relative to the sequence of all activations 
and invocations that have been created over time within the process. 


The associated program pointer is a system pointer that locates the program associated with the invo- 
cation entry. 


The invocation number is a number that uniquely identifies each invocation in the invocation stack. 
When an invocation is allocated, the invocation number of the new invocation entry is one more than 
that in the calling invocation. The first invocation in the current process state has an invocation 
number of one. 


The invocation type indicates how the associated program was invoked. 
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The invocation mark indicates the point at which this invocation entry was allocated relative to the 
sequence of all activations and invocations that have been created over time within the process. This 
is set from the incremented mark counter value for each new invocation added to the invocation stack. 


If the invocation type is a non-bound program the instruction id field will contain the instruction number 
which specifies the number of the instruction last being executed when the invocation passed control 
to the next invocation on the stack. If the invocation type is a bound program entry or a procedure, the 
instruction id field will contain the statement identifier, which is a compiler supplied number which 
allows the compiler to to identify the source statement associated with a particular sequence of 
instructions. 


Note: If the program is damaged or destroyed or if a statement identifier was not supplied by the 
compiler, a value of 0 is set. 


The suspend point is a suspend pointer which identifies the instruction last being executed when the 
invocation passed control to the next invocation on the stack. 


The fields labeled reserved are currently reserved for future use. These fields may be altered by this 
instruction depending upon the particular implementation of the machine. Any values set into these 
fields are meaningless. 


The first 4 bytes of the materialization identifies the total number of bytes provided for use by the 
instruction. This value is supplied as input to the instruction and is not modified by the instruction. A 
value of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identifies the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- 
tion requested, the excess bytes are unchanged. 


No exceptions are signaled in the event that the receiver contains insufficient area for the 
materialization, other than the materialization length exception described previously. 


When the materialization is performed for a process other than the one executing this instruction, the 
instruction attempts to interrogate, snapshot, the invocation stack of the other process concurrently 
with the ongoing execution of that process. In this case, the interrogating process and subject process 
may have interleaving usage of the processor resource. Due to this, the accuracy and integrity of the 
materialization is relative to the state, static or dynamic, of the invocation stack in the subject process 
over the time of the interrogation. If the invocation stack in the subject process is in a very static state, 
not changing over the period of interrogation, the materialization may represent a good approximation 
of a snapshot of its invocation stack. To the contrary, if the invocation stack in the subject process is 
in a very dynamic state, radically changing over the period of interrogation, the materialization is 
potentially totally inaccurate and may describe a sequence of invocations that was never an actual 
sequence that occurred within the process. In addition to the above exposures to inaccuracy in 
attempting to take the snapshot, the ongoing status of the invocation stack of the subject process may 
substantially differ from that reflected in the materialization, due to its continuing execution after com- 
pletion of this instruction. 


~~ 


When the materialization is performed for the process executing this instruction, it does provide an 
accurate reflection of the status of the process’ invocation stack. In this case, concurrent execution of 
this instruction with execution of other instructions in the process is precluded. 
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Authorization Required 
* Process control special authorization 
— For materializing a different process than the one executing this instruction 
¢ Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
¢ Materialization 


— Contexts referenced for address resolution 


Exceptions 


Exception 1 
06 Addressing 
01 space addressing violation X 
02 boundary alignment xX 
03 range X 
06 optimized addressability invalid X 


08 Argument/parameter 


01 parameter reference violation Xx 


0A Authorization 


01 unauthorized for operation X 


10 Damage encountered 
04 system object damage state 


44 partial system object damage 


1¢C Machine-dependent exception 


03 machine storage limit exceeded 


20 Machine support 
02 machine check 


03 function check 


22 Object access 
01 object not found X 


x 


02 object destroyed 
03 object suspended Xx 


24 Pointer specification 
01 pointer does not exist Xx 
02 pointer type invalid X 


28 Process state 


02 process control space not associated with a process 


2E Resource contro! limit 
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Operands 
Exception 1 2 Other 
01 user profile storage lint exceeded X 
32 Scalar specification 
01 scalar type invalid X X 
02 scalar attributes invalid X Xx 
36 Space management 
01 space extension/truncation X 
38 Template specification 
03 materialization length X 
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Op Code (Hex) Operand 1 Operand 2 
0512 Receiver Pointer 


Operand 1: Space pointer. 


| Operand 2: System pointer, space pointer data object, data pointer, instruction pointer, invocation 
| pointer, procedure pointer, label pointer, or suspend pointer. 


| ILE access 


MATPTR ( 
receiver : space pointer; 
var pointer : pointer 


) 


Description: The materialized form of the pointer object referenced by operand 2 is placed in operand 
1. 


The format of the materialization is: 


e Materialization size specification Char(8) 
— Number of bytes provided for materialization | Bin(4) 
— Number of bytes available for materialization Bin(4) 

¢ Pointer type Char(1‘) 


Hex 01 = System pointer 
Hex 02 = Space pointer 
Hex 03 = Data pointer 

Hex 04 = Instruction pointer 
| Hex 05 = Invocation pointer 
| Hex 06 = Procedure pointer 
| Hex 07 = Label pointer 
| 

| 


Hex 08 = Suspend pointer 


¢ Pointer description Char(*) 


| Pointer description depends on the pointer type. One of the following pointer type formats is used. 
| © System pointer description Char(68) 


The system pointer description identifies the object addressed by the pointer and the context which 
the object specifies as its addressing context. 


— Context identification Char(32) 
- Context type Char(1) 
- Context subtype Char(1) 
- Context name Char(30) 
— Object identification Char(32) 
- Object type Char(1) 
- Object subtype Char(1) 
- Object name Char(30) 
— Pointer authorization Char(2) 
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- Object control Bit O 
- Object management Bit 1 
- Authorization pointer Bit 2 
- Space authority Bit 3 
- Retrieve Bit 4 
- Insert Bit 5 
- Delete Bit 6 
- Update Bit 7 
- Ownership Bit 8 
- Reserved (binary 0) Bits 9-15 
— Pointer target information Char(2) 
- Pointer target accessible from user state Bit 0 
- Reserved (binary 0) Bits 1-15 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the 
instruction. This value is supplied as input to the instruction and is not modified by the instruction. 
A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 
ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the 
information requested, then the excess bytes are unchanged. No exceptions (other than the 
materialization length exception) are signaled in the event that the receiver contains insufficient 
area for the materialization. 


Note: If the object addressed by the system pointer specifies that it is not addressed by a context 
or if the context is destroyed, the context identification field is hex 00. If the object is 
addressed by the machine context, a context type field of hex 81 is returned. No verification 
is made that the specified context actually addresses the object. 


The following lists the object type codes for system object references: 


Value 
(Hex) Object Type 


01 Access group 

02 Program 

03 Module 

04 Context 

06 Byte string space 

07 Journal space 

08 User profile 

Q9 Journal port 

OA Queue 

OB Data space 

ole Data space index 

OD Cursor 

OE Index 

OF Commit block 

10 Logical unit description 
11 Network description 

12 Controller description 
13 Dump space 

14 Class of service description 
15 Mode Description 

16 Network interface description 
17 Connection list 
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Queue space 

Space 

Process control space 
Authorization list 
Dictionary 


Note: Only the authority currently stored in the system pointer is materialized. 


If the pointer target accessible from user state field has a value of 1, then the system pointer 


addresses an object that is in user domain. If the pointer target accessible from user state field 


has a value of 0, then the system pointer addresses an object that is not in user domain. 


Data pointer description 


Char(75) 


The data pointer description describes the current scalar and array attributes and identifies the 
space addressability contained in the data pointer. 


Scalar and array attributes 
- Scalar type 


Hex 00 = Signed binary 
Hex 01 = Floating-point 
Hex 02 = Zoned decimal 


Hex 03 = Packed decimal 
Hex 04 = Character 

Hex 06 = Onlyns 

Hex 07 = Onlys 

Hex 08 = Either 


Hex 09 = Open 
Hex 0A = Unsigned binary 


- Scalar length 
If binary, character, floating-point, Onlyns, Onlys, Either, or Open: 
e Length 
If zoned decimal or packed decimal: 


e Fractional digits 
¢ Total digits 


- Reserved (binary 0) 
Data pointer space addressability 
- Context identification 


e Context type 
e Context subtype 
« Context name 


- Object identification 


e Object type 
e Object subtype 
e Object name 


- Offset into space 


Char(7) 
Char(1) 


Char(2) 


Bits 0-15 


Bits 0-7 
Bits 8-15 


Bin(4) 
Char(68) 
Char(32) 


Char(1) 
Char(1) 
Char(30) 


Char(32) 


Char(1) 
Char(1) 
Char(30) 


Bin(4) 


Note: If the object containing the space addressed by the data pointer is not addressed by a 
context, the context field is hex 00. If the object is addressed by the machine context, a 


context type field of hex 81 is returned. 
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Support for usage of a Data Pointer describing an Onlyns, Onlys, Either, or Open scalar 
value is limited. For more information, refer to the Copy Extended Characters Left 
Adjusted With Pad, Set Data Pointer Attributes, and Create Cursor instructions. 


Space pointer description 


Char(70) 


The space pointer description describes space addressability contained in the space pointer. 


— Context identification Char(32) 
- Context type Char(1) 
- Context subtype Char(1) 
- Context name Char(30) 

— Object identification Char(32) 
- Object type Char(1) 
- Object subtype Char(1) 
- Object name Char(30) 

— Offset into space Bin(4) 

— Pointer target information Char(2) 
- Pointer target accessible from user state Bit 0 
- Reserved (binary 0) Bits 1-15 


lf the pointer target accessible from_user state field has a value of 1, then the space pointer 
addresses a space that is in user domain and is writeable when the process is running in user 
state. If the pointer target accessible from user state field has a value of 0, then the space refer- 
enced by the pointer is either not in user domain or it is not writeable when the process is running 
in user state. 


Note: If the object containing the space addressed by the space pointer is not addressed by a 
context, the context field is hex 00. If the object is addressed by the machine context, a 
context type field of hex 81 is returned. 


Instruction pointer description Char(68) 


The instruction pointer description describes instruction addressability contained in the instruction 


pointer. 


— Context identification Char(32) 
- Context type Char(1) 
- Context subtype Char(1) 
- Context name Char(30) 

— Program identification Char(32) 
- Program type Char(1) 
- Program subtype Char(1) 
- Program name Char(30) 

— Instruction number Bin(4) 


lf the program containing the instruction currently being addressed by the instruction pointer is not 
addressed by a context, the context field is hex 00. 
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« Invocation pointer description Char(23) 


The invocation pointer description describes invocation addressability contained in the invocation 
pointer. 


— Pointer status Char(1) 
- Process object no longer exists Bit 0 
- Pointer is from another process Bit 1 
- Reserved (binary 0) Bits 2-7 
— Reserved (binary 0) Char(6) 
— Containing process System pointer 


Process object no longer exists 
If this bit has a value of 1, then the process object (invocation) referenced by the pointer no 
longer exists. 


Pointer is from another process 
If this bit has a value of 1, then the process object (invocation) referenced by the pointer exists 
but belongs to a process other than the current one. 


Containing process 
A system pointer to the process control space object to which the process object belongs. A 
null pointer is returned if the process object (invocation) no longer exists. 


Procedure pointer description Char(55) 


The procedure pointer description describes the activation and procedure addressability contained 
in the procedure pointer. 


— Pointer status Char(1) 
- Process object no longer exists Bit 0 
- Pointer is from another process Bit 1 
- Referenced program cannot be accessed Bit 2 
- Reserved (binary 0) Bits 3-7 
— Reserved (binary 0) Char(6) 
— Module number Ubin(4) 
— Procedure number Ubin(4) 
— Activation mark Ubin(4) 
— Activation group mark Ubin(4) 
— Containing program System pointer 
— Containing process System pointer 


Process object no longer exists 
If this bit has a value of 1, then the process object referenced by the pointer (the activation) no 
longer exists. All of the remaining information is returned as binary Zeros. 


Pointer is from another process 
If this bit has a value of 1, then the process object referenced by the pointer belongs to a 
process other than the current one. With the exception of the containing process pointer, all of 
the remaining information is returned as binary zeros. 


Referenced program cannot be accessed 
If this bit has a value of 1, then the program referenced by the pointer could not be accessed to 
extract the program-related information. The may be because the program is damaged, sus- 
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pended, compressed, or destroyed. The program pointer. module number. and procedure 
number are returned as binary zeros. 


Module number J 
Index in the module list of the bound program for the module whose activation the pointer 
addresses. 


Procedure number 
Index in the procedure list of the module for the procedure addressed by the pointer. 


Activation mark 
The activation mark of the activation that contains the activated procedure. Zero if the 
program activation no longer exists. 


Activation group mark 
An activation group mark of the activation group that contains the activated procedure. Zero if 
the program activation no longer exists. 


Containing program 
A system pointer to the program object that contains the procedure. Null if the program acti- 
vation no longer exists. 


Containing process 
A system pointer to the process control space object which contains the procedure’s activation 
group. A null pointer is returned if the process control space object no longer exists, of if it is 
no longer possible to determine the containing process for a destroyed activation group. 


Label pointer description | Char(*) 
The label pointer description describes instruction addressability contained in the label pointer. 
4 
— Pointer status Char(1) J 
- Reserved (binary 0) Bit 0 
- Reserved (binary 0) Bit 1 
- Referenced program is damaged, suspended, Bit 2 
compressed or destroyed 
- Reserved (binary 0) Bits 3-7 
— Reserved (binary 0) Char(6) 
— Moduie number Ubin(4) 
— Procedure number Ubin(4) 
— Number of statement IDs Ubin(4) 
— Internal identifier Char(4) 
— Containing program System pointer 
— Statement ID (repeated) Ubin(4) 


Referenced program is damaged, suspended, compressed, or destroyed 
If this bit has a value of 1, then the program referenced by the pointer could not be accessed to 
extract the remaining information. The remainder of the template is binary zeros with the 
exception of the program pointer, which will be binary zeros if the program has been destroyed 
or so seriously damaged that its identity cannot be determined. 


Module number 
Index in the module list of the bound program for the module containing the label. 


Procedure number S) 
Index in the procedure list of the module for the procedure containing the label. 
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Number of statement IDs 
Number of entries in the statement ID list. (Multiple statement IDs may be associated with a 
single location in the created program due to optimizations that combine similar code 
sequences.) 


Internal identifier 
A machine-dependent value which identifies the label relative to the the internal structure of 
the program. For use by service personnel. 


Containing program 
A system pointer to the program object that contains the labe!. 


Statement ID 
Each statement ID is a compiler-supplied unsigned Bin(4) number which allows the compiler to 
identify the source statement associated with a particular sequence of instructions. 


Suspend pointer description Char(*) 


The suspend pointer description describes instruction addressability contained in the suspend 
pointer. 


— Pointer status Char(1) 

- Reserved (binary 0) Bit O 

- Reserved (binary 0) Bit 1 

- Referenced program is damaged, suspended, Bit 2 

compressed or destroyed 

- Reserved (binary 0) ‘Bits 3-7 
— Reserved (binary 0) Char(6) 
— Module number Ubin(4) 
— Procedure number Ubin(4) 
— Number of statement IDs Ubin(4) 
— Internal identifier Char(4) 
— Containing program System pointer 
— Statement ID (repeated) Ubin(4) 


Referenced program is damaged, suspended, compressed, or destroyed 
If this bit has a value of 1, then the program referenced by the pointer could not be accessed to 
extract the remaining information. The remainder of the template is binary zeros with the 
exception of the program pointer, which will be binary zeros if the program has been destroyed 
or so seriously damaged that its identity cannot be determined. 


Module number 
Index in the module list of the bound program for the module containing the suspend point. 


Procedure number 
Index in the procedure list of the module for the procedure containing the suspend point. 


Number of statement IDs 
Number of entries in the statement ID list. (Multiple statement IDs may be associated with a 
single location in the created program due to optimizations that combine similar code 
sequences.) 


Internal identifier 
A machine-dependent value which locates the suspend point relative to the the internal struc- 


ture of the program. For use by service personnel. 
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Containing program 
A system pointer to the program object that contains the suspend point. 


Statement ID >) 


Each statement ID is a compiler-supplied unsigned Bin(4) number which allows the compiler to 
identify the source statement associated with a particular sequence of MI instructions. 


Note: For suspend pointers which address non-bound programs, module number and procedure 
number are returned as binary zeros, and the statement ID list is returned with one value 
which is the MI instruction number of the suspend point. 


If the pointer is a system pointer or a data pointer and is initialized but unresolved, the pointer is 
resolved before the materialization occurs. 


This instruction will tolerate a damaged object referenced by operand 2 when operand 2 is a resolved 
pointer. The instruction will not tolerate a damaged context(s) or damaged programs when resolving 
pointers. Also, as a result of damage or abnormal machine termination, this instruction can indicate 
that an object is addressed by a context, when in fact the context will not show this as an addressed 
object. 


A space pointer machine object cannot be specified for operand 2. 


Exceptions 
, Operands 
Exception 1 2 Other 
06 Addressing | 
01 space addressing violation X X > 
02 boundary alignment X X 
03 range X X 
04 external data object not found X 
06 optimized addressability invalid X X 
08 Argument/parameter 
01 parameter reference violation X X 
10 Damage encountered 
04 system object damage state X X X 
05 authority verification terminated due to damaged object X 
44 partial system object damage X X X 
ic Machine-dependent exception 
03 machine storage limit exceeded X 
20 Machine support 
02 machine check X 
03 function check X 
22 Object access 
01 object not found X X 
02 object destroyed X X 
03 object suspended X X 
07 authority verification terminated due to destroyed object X 
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24 


2E 


32 


36 


38 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 


01 scalar type invalid 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 
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Operands 

1 2 Other 
X 

X X 

X X 
X 

X 
X 

X 
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Op Code (Hex) Operand 1 Operand 2 Operand 3 ) 
0513 Receiver Source Length 


Operand 1: Space pointer. 
Operand 2: Space pointer. 


Operand 3: Binary scalar. 


ILE access 
MATPTRL ( 
receiver : space pointer; 
source : space pointer; 
var length : signed binary 


) 


Description: This instruction finds the pointers in a subset of a space and produces a bit mapping of 
their relative locations. 


The area addressed by the operand 2 space pointer is scanned for a length equal to that specified in 
operand 3. A bit in operand 1 is set for each 16 bytes of operand 2. The bit is set to binary 1 if a 
pointer exists in the operand 2 space, or the bit is set to binary 0 if no pointer exists in the operand 2 


space. | 


Operand 1 is a space pointer addressing the receiver area. One bit of the receiver is used for each 16 
bytes specified by operand 3. If operand 3 is not a 16-byte multiple, then the bit position in operand 1 
that corresponds to the last (odd) bytes of operand 2 is set to 0. Bits are set from left to right (bit 0, bit 
1,...) in operand 1 as 16-byte areas are interrogated from left to right in operand 2. The number of bits 
set in the receiver is always a multiple of 8. Those rightmost bits positions that do not have a corre- 
sponding area in operand 2 are set to 0. 


The format of the operand 1 receiver is: 


e Template size specification Char(8) 
— Number of bytes provided by the user Bin(4) 
— Number of bytes available for materialization Bin(4) 

¢ Pointer locations Char(*) 


Operand 2 must address a 16-byte aligned area; otherwise, a boundary alignment (hex 0602) exception 
is signaled. If the value specified by operand 3 is not positive, the scalar value invalid (hex 3203) 
exception is signaled. 


The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruc- 
tion. This value is supplied as input to the instruction and is not modified by the instruction. A value 
of less than 8 causes the materialization length (hex 3803) exception to be signaled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 

ized. The instruction materializes as many bytes as can be contained in the area specified as the 
receiver. If the byte area identified by the receiver is greater than that required to contain the informa- S| 
tion requested, then the excess bytes are unchanged. No exceptions (other than the materialization 
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length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for 
materialization. 


Exceptions 


Exception 1 2 3 Other 
06 Addressing 
01 space addressing violation 
02 boundary alignment 


03 range 


x KK RK 
x KK K 
x KK KK 


06 optimized addressability invalid 


08 Argument/parameter 


01 parameter reference violation X X X 


10 Damage encountered 
04 system object damage state X X X X 
44 partial system object damage X X X X 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check Xx 
03 function check X 


22 Object access 
01 object not found X 
02 object destroyed X X 
03 object suspended X X X 
08 object compressed X 


Pa 


24 Pointer specification 
01 pointer does not exist X X X 


02 pointer type invalid X X X 


2E Resource contro! limit 


01 user profile storage limit exceeded X 


32 Scalar specification 


03 scalar value invalid Xx 


36 Space management 


01 space extension/truncation X 


38 Template specification 


03 materialization length exception X 
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Op Code (Hex) Operand 1 Operand 2 ) 
O53E Receiver Object 


Operand 1: Space pointer. 


Operand 2: System pointer. 


ILE access 
MATSOBJ ( 
receiver : space pointer; 
var object : system pointer 


) 


Description: This instruction materializes the identity and size of a system object addressed by the 
system pointer identified by operand 2. It can be used whenever addressability to a system object is 
contained in a system pointer. 


The format of the materialization is: 


¢ Materialization size specification Char(8) 
— Number of bytes provided by the user Bin(4) 
— Number of bytes available for Bin(4) 
materialization = 
¢ Object state attributes Char(2) J 
— Suspended state Bit 0 


QO = Not suspended 
1 = Suspended 


— Damage state Bit 1 
0 = Not damaged 
1 = Damaged 

— Partial damage state Bit 2 


0 = No partial damage 
1 = Partial damage 


— Existence of addressing context Bit 3 


QO = Not addressed by a temporary context 
1 = Addressed by a temporary context 


— Dump for previous release permitted Bit 4 
0 = Dump for previous release not permitted. 
1 = Dump for previous release permitted. 
— Object compressed Bit 5 
0 = Object not compressed 
1 = Object compressed (partially or completely) 
~ ASP overflow Bit 6 2a 


0 = No part of the object has overflowed its ASP 
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1 = Some part of the object has overflowed its ASP 
— Reserved (binary 0) 
Context identification 
— Context type 
— Control subtype 
— Context name 
Object identification 
— Object type 
— Object subtype 
— Object name 
Timestamp of creation 
Size of associated space 
Object size 
Owning user profile identification 
— User profile type 
— User profile subtype 
— User profile name 
Timestamp of last modification 
Recovery options 
Performance class 
Initial value of space 
Object audit attribute 


Hex 00 = No audit for this object 
Hex 02 = Audit change for this object 
Hex 03 = Audit read and change for this object 


Bits 7-15 
Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(32) 
Char(1) 
Char(1) 
Char(30) 
Char(8) 
Bin(4) 
Bin(4) 
Char(32) 
Char(‘) 
Char(1) 


Char(30) 


Char(8) 
Char(4) 
Char(4) 
Char(1) 
Char(1) 


Hex 04 = Audit read and change for this object if the user profile is being audited 


Reserved 
Object authorization list (AL) status 


0 = Object not in an AL 
1 = Object in AL 


Authorization list identification 


— Authorization list (AL) status 


0 = Valid AL 
1 = Damaged AL 
2 = Destroyed AL (no name below) 


— Reserved 

— Authorization list type 

— Authorization list subtype 
— Authorization list name 


Dump for previous release reason code 
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Char(2) 
Bin(2) 


Char(48) 
Bin(2) 


Char(14) 
Char(1) 
Char(‘1) 
Char(30) 
Bit(64) 
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¢ Maximum possible associated space size Bin(4) 
« Timestamp of last use of object Char(8) 
e Count of number of days object was used Ubin(2) 
e Program attributes Char(2) 
— Program state provided Bit O 
0 = No program state value 


1 = Program state value present 
— Reserved (binary 0) Bits 1-7 
— Type of program Char(1) 


Hex 00 = Original program 
Hex 01 = Bound program 
Hex 02 = Service program 


¢ Domain of object Char(2) 

e Program state for program or module Char(2) 

e Ml-supplied information Char(8) 

¢ Earliest compatible release Char(2) 
— Reserved Bits 0-3 
— Version Bits 4-7 
— Release Bits 8-11 
— Modification level Bits 12-15 

e Object size in pages Ubin(4) 

e Reserved Char(110) 


Additional Description:: This instruction will tolerate a damaged object referenced by operand 2 when 
operand 2 is a resolved pointer. The instruction will not tolerate a damaged context(s) or damaged 
programs when resolving pointers. Also, as a result of damage or abnormal machine termination, this 
instruction can indicate that an object is addressed by a context, when in fact the context will not show 
this as an addressed object. The Modify Addressability instruction can be used to correct this 
problem. 


The existence of addressing context field indicates whether the previously (or currently) addressing 
context was (iS) temporary. This field is 0 if the object was (is) not addressed by a temporary context. 


The dump for previous release permitted field will indicate if the object is eligible for a Request I/O 
instruction in which a dump for previous is requested’. When this field indicates that the object is not 
eligible, the dump for previous release reason code can be used to determine why the object is not 
eligible. 


The object compressed field indicates whether the encapsulated part of the object is either partially or 
completely compressed. The encapsulated part(s) of some object types can be compressed by object- 
specific create or modify instructions. For example, the executable and observation parts of a program 
object can be compressed and decompressed by the Modify Program instruction, and can also be 
decompressed implicitly by machine operation (see the Modify Program instruction for details). Use 
the object-specific materialization instruction for this type of object (for example, the Materialize 


1 ’Previous release’ refers to the previous mandatory release. This is release N-1, mod level zero when release N is the 


current release. (For version 2, release 1.1, the previous mandatory release is version 1, release 3.0.) 
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Program instruction for program objects) to determine exactly which part(s) of the object are com- 
pressed. 


The ASP overflow field indicates whether any part of the object is stored in an ASP other than the ASP 
specified at the time the object was created. If any object created in one ASP has parts that are ina 
different ASP (due to lack of sufficient available storage in the original ASP), then none of the objects 
in the first ASP are protected in the event of a failure of any other ASP in the system. By deleting 
objects that have overflowed, however, it may be possible to eliminate the ASP overflow condition and 
restore the protection that ASPs provide. Use the object-specific materialization instruction for this type 
of object to determine what ASP was specified at the time the object was created. 


If the object addressed by the system pointer specifies that it is not addressed by a context or if the 
context is destroyed, the context type field is hex 00. If the object is addressed by the machine 
context, a context type field of hex 81 is returned. No verification is made that the specified context 
actually addresses the object. 


Valid object type fields and their meanings are: 


Value 
(Hex) Object Type 


01 Access group 

02 Program 

03 Module 

04 Context 

06 Byte string space 

07 Journal space 

08 User profile 

09 Journal port 

OA Queue 

0B Data space 

OC Data space index 

0D Cursor 

OE Index 

OF Commit block 

10 Logical unit description 
11 Network description 

12 Controller description 
13 Dump space 

14 Class of Service Description 
15 Mode Description 

16 Network interface description 
17 Connection list 

18 Queue space 

19 Space 

1A Process control space 
1B Authorization List 

1c Dictionary 


The timestamp field is materialized as an 8-byte unsigned binary number in which bit 41 is equal to 
1024 microseconds. The timestamp of creation field is implicitly set when an object is created. 


If the object has an associated space, the maximum possible associated space size field will be 


returned with a value which represents the maximum size to which the associated space can be 
extended. This value depends on the internal packaging of the object and its associated space as well 
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as (possibly) the maximum space size field as optionally specified during the create of the object (or 
on the Create Duplicate Object instruction, if that is how the object was created). 


The object size field will contain the size of the object in bytes up to a value of 2G-1 (2147483647). If 
the object’s size is greater than this, a value of zero will be returned in the object size field. In this 
case, the object size in pages field should be used to get the object’s actual size. This field will always 
contain the object’s true size in number of pages. 


If the object is a temporary object and is, therefore, owned by no user profile, the user profile type field 
is assigned a value of hex 00. 


The timestamp of last modification field is explicitly set by the Modify System Object instruction. It is 
implicitly set, except for the objects restricted below, by any instruction or IMPL function that modifies 
or attempts to modify an object attribute value or an object state. The timestamp of last modification 
field is only ensured as part of the normal ensuring of objects. 


Implicit setting of the timestamp of last modification field is restricted for the following objects and will 
only occur for generic, nonobject specific, operations on them such as Rename Object for example. 

e Logical unit description 

e Controller description 

e Network description 

e Access group 

e Queue 
No modification time stamp will be provided for the following objects and a value of zero will be 
returned in the materialization template for the modification time stamp. 

¢ Process control space 
The object authorization list status field indicates whether or not the object is contained in an authori- 
zation list. If it is, the authorization list identification information provides the name of the authorization 


list, except when the authorization list is indicated as destroyed, in which case, the name information 
is meaningless. 


The dump for previous release reason code can be used to determine why the object is not eligible 
according to the dump for previous release permitted field. Currently reason codes are only archi- 
tected for programs. The reason code structure for programs is mapped as follows. Note that more 
than one reason may be returned. 


¢ Program dump for previous release Bit(64) 

reason code 

— Language version and release reason Bit O 
O = Language version and release is not a reason 
1 = Language version and release is one reason 

— Level of machine instructions used Bit 1 i 
reason 
O = The level of machine instructions used in the program is not a reason 
1 = Machine instructions not available in the previous release are used 

— Program observability reason Bit 2 


0 = Lack of program observability is not a reason 
1 = Program is not observable and must be to be moved to previous release 


— Reserved Bits 3-63 
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The timestamp of last use of object field and the count of number of days object was used field are set 
by the Modify System Object instruction or by the Call External or Transfer Control instructions on the 


objects first use on that day. The timestamp value is only good for the date. The time value obtained 
from this timestamp is not accurate. 


The type of program field indicates the Program Model of a program object, which is determined by 
how the program was created. It is only present when operand 2 points to a program object. This 
field is necessary since the object type and object subtype do not provide enough information to iden- 
tify the Program Model of a program object. Knowing the program type is useful in selecting appro- 
priate program specific instructions. 


The domain of object field contains the value of the state under which a program or procedure must be 
running to access this object. 


The program state for program or module field contains the state under which the program runs. It is 
only present when the program state provided flag is on. 


The Ml-supplied information is simply an 8 byte character field which can be set into an object with the 
Modify System Object (MODSOB,) instruction and materialized with the Materialize System Object 
(MATSOBJ) instruction. The machine has no knowledge or dependencies on the content of this field. 


The earliest compatible release field contains the earliest release that in which the object can be used 
in. 


Authorization Required 
e Retrieve 


— Contexts referenced for address resolution 


Lock Enforcement 
e Materialize 
— Operand 2 


— Contexts referenced for address resolution 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X X 

02 boundary alignment X X 

03 range X X 

06 optimized addressability invalid X X 
08 Argument/parameter 

01 parameter reference violation X X 
0A Authorization 

01 unauthorized for operation X 
10 Damage encountered 

04 system object damage state X X X 
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Operands 


Exception 1 2 Other 
05 authority verification terminated due to damaged object X > 


44 partial system object damage X X X 


1A Lock state 


01 invalid lock state Xx 


1C Machine-dependent exception 


03 machine storage limit exceeded X 


20 Machine support 
02 machine check X 
03 function check X 


22 Object access 
01 object not found X X 


x< 
< 


02 object destroyed 
03 object suspended X X 
07 authority verification terminated due to destroyed object X 


08 object compressed X 


24 Pointer specification 
01 pointer does not exist X X 


02 pointer type invalid X X 


ae 


2E Resource control limit ; 
01 user profile storage limit exceeded X 


32 Scalar specification 


01 scalar type invalid X X 


36 Space management 


01 space extension/truncation X 


38 Template specification 


03 materialization length exception X 
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This chapter describes all instructions used for machine interface support functions. These 
instructions are arranged in alphabetic order. For an alphabetic summary of all the instructions, see 
Appendix A, 


Materialize Machine Attributes (MATMATR) ......... 0.0... 0 eee ee ee 22-4 
Materialize Machine Data (MATMDATA) ........... 0.000 ee ee ee ee 22-30 
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Op Code (Hex) Operand 1 Operand 2 Ja 
0636 Materialization Machine attributes 


Operand ?: Space pointer. 


Operand 2: Character(2) scalar or Space pointer. 


ILE access 

MATMATR1 ( 

materialization : Space pointer; 
var machine_attributes : aggregate 
) 
OR 
MATMATR2 ( 

materialization : space pointer; 

machine_attributes : space pointer 
) 


Warning: The following information is subject to change from release to release. Use it with caution 

and be prepared to adjust for changes with each new release. 

Description: The instruction makes available the unique values of machine attributes. The values of ) 
various machine attributes are placed in the receiver. 


Operand 2 specifies options for the type of information to be materialized. Operand 2 is specified as 
an attribute selection value (Character(2) scalar). 


The machine attributes are divided into nine groups. Byte 0 of the attribute selection operand specifies 
from which group the machine attributes are to be materialized. Byte 1 of the options operand selects 
a specific subset of that group of machine attributes. 


Operand 1 specifies a space pointer to the area where the materialization is to be placed. The format 
of the materialization is as follows: 


¢« Materialization size specification Char(8) 
— Number of bytes provided by the user Bin(4) 
— Number of bytes available for materialization Bin(4) 

e Attribute specification Char(*) 


(as defined by the attribute selection) 


The first 4 bytes of the materialization (operand 1) identify the total number of bytes provided for use 
use by the instruction. This value is supplied as input to the instruction and is not modified by the 
instruction. A value of less than 8 causes the materialization length (hex 3803) exception to be sig- 
naled. 


The second 4 bytes of the materialization identify the total number of bytes available to be material- 

ized. The instruction materializes as many bytes as can be contained in the area specified as the J 
receiver. If the byte are identified by the receiver is greater than that required to contain the informa- 

tion requested for materialization, then the excess bytes are unchanged. No exceptions (other than the 
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materialization length (hex 3803) exception) are signaled in the event that the receiver contains insuffi- 
cient area for the materialization. 


The machine attributes selected by operand 2 are materialized according to the following selection 
values: 


Selection Attribute 
Value Description 


Hex 0004 Machine serial identification 


The machine serial identification that is materialized is an 8-byte character field that con- 
tains the unique machine identifier. 


Hex 0100 Time-of-day clock 


The time-of-day clock provides a consistent measure of elapsed time. The maximum 
elapsed time the clock can indicate is approximately 143 years. 


The time-of-day clock is a 64-bit unsigned binary counter with the following format: 
8 Paneer ere arene 41 42 reserved 63 
The bit positions of the clock are numbered from 0 to 63. 


The clock is incremented by adding a 1 in bit position 41 every 1024 microseconds. Bit posi- 
tions 42 through 63 are used by the machine and have no special meaning to the user. Note 
that these bits (42-63) may contain either binary 1’s or binary 0’s. 


The maximum unsigned binary value that the time of day clock can be modified to contain is 
hex DFFFFFFFFFFFFFFF. 


Hex 0104 Primary Initial process definition template 


The primary initial process definition template is used by the machine to perform an initial 
process load. 


No check is made and no exception is signaled if the values in the template are invalid; 
however, the next initial process load will not be successful. 


Hex 0108 Machine initialization status record 


The MISR (machine initialization status record) is used to report the status of the machine. 
The status is initially collected at IPL and then updated as system status changes. 


The materialize format of the MISR is as follows: 


e MISR status Char(8) 
— Restart IMPL Bit 0 
0 = IMPL was not initiated by the Terminate instruction 
1 = IMPL was initiated by the Terminate instruction 
— Manual power on Bit 1 
O = Power on not due to Manual power on 
1 = Manual power on occurred 
— Timed power on Bit 2 


0 = Power on not due to Timed power on 
1 = Timed power on occurred 


— Remote power on Bit 3 
0 = Power on not due to Remote power on 
1 = Remote power on occurred 

— Auto-power restart power on Bit 4 
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Power on not due to Auto-power restart power on 


1 = Auto-power restart power on occurred 


Uninterrupted power supply 
(UPS) battery low 


0 = UPS battery not low 
1 = UPS battery low 


Uninterrupted power supply 
(UPS) bypass active 


0 UPS bypass not active 
1 = UPS bypass active 


Utility power failed, running on UPS 


0 = Running on utility power 
1 = Running on UPS 


Uninterrupted power supply installed 


0 UPS not installed 
1 UPS installed, ready for use 


Operation Panel battery failed 


0 = Operation Panel battery good 
1 = Operation Panel battery failed 


Operation Panel self test failed 


0 
1 = Operation Panel self test failed 


Console status 


0 = Console is operative 
1 = Console is inoperative 


Console state 


0 = Console is not ready 
1 = Console is ready 


OS Level mismatch 


Bit 5 


Bit 6 


Bit 7 


Bit 8 


Bit 9 


“Bit 10 


Operation Panel self test successful 


Bit 11 


Bit 12 


Bit 13 


O = Machine and OS version levels match. 
4 = Machine and OS version levels mismatch 


Reserved 


Primary console status 


0 = Not using Primary console 
1 = Using Primary console 
Reserved 


ASCII console status 


O = Not using ASCII console 
1 = Using ASCII console 


Termination status 


0 Normal (TERMMPR) 
4 = Abnormal 


lI 


Duplicate user profile 
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Bit 14 
Bit 15 


Bit 16 
Bit 17 


Bit 18 


Bit 19 
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| 
Damaged user profile 
(AIPL only) 


0 
| 


Not damaged, user profile used 
Damaged user profile, profile del 


— 
— 


Damaged machine context 


0 = Not damaged 
1 = Machine context damaged 


Object recovery list status 


0 
1 


Complete 
Incomplete 


Recovery phase completion 


0 = Complete 
1 = Incomplete 


Most recent machine termination 
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Not duplicate, new user profile created 
Duplicate found and used by AIPL 


Bit 20 


eted and recreated 
Bit 21 


Bit 22 


Bit 23 


Bit 24 


0 = Objects ensured 

1 = Object(s) not ensured at most recent machine termination 

Last MISR reset Bit 25 

0 = Object(s) ensured on every machine termination 

1 = Object(s) not ensured on every machine termination since last MISR reset 
Reserved Bit 26-27 
IPL Mode Bit 28-29 
(can be materialized and modified) 

00 = DST and BOSS in unattended mode 

10 = DST and BOSS is attended mode 

Service Processor power on Bit 30 

0 = Not first service processor power on 

1 = First service processor power on 

MISR damage Bit 31 

0 = MISR not damaged 

1 = MISR damaged, information reset to default values 

Auto keylock position Bit 32 

0 = Keylock not in auto position 

1 = Keylock in auto position 

Normal keylock position Bit 33 

0 = Keylock not in normal position 

1 = Keylock in normal position 

Manual keylock position Bit 34 

0 = Keylock not in manual position 

1 = Keylock in manual position 

Secure keylock position Bit 35 
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0 
1 


— Tower two presence on 9404 Bit 36 
system unit 


Keylock not in secure position 
Keylock in secure position 


O = Tower two not present 
1 Tower two present 


— Battery status for tower one Bit 37 
on 9404 system unit 


OQ = Battery good for tower one 
1 = Battery low for tower one 


— Battery status for tower Bit 38 
two on 9404 


0 = Battery good for tower two 
1 Battery low for tower two 


— Termination due to utility power Bit 39 
failure and user specified delay time exceeded 


0 
1 


— Termination due to utility power Bit 40 
failure and battery low 


Delay time not exceeded 
Utility failure and delay time exceeded 


0 = Battery not low 
1 = Utility failure and battery low 


— Termination due to forced Bit 41 
microcode completion 


0 = Not forced microcode completion 
1 = Termination due to forced microcode completion 


— Auto power restart disabled Bit 42 
due to utility failure 


0 
1 


— Reserved Bit 43 
— Spread the Operating System Bit 44 


Auto power restart not disabled 
Auto power restart disabled 


0 = Do not spread the Operating System 
1 = Spread the Operating System 


— Install from Disk/Tape Bit 45 


O = Install from tape 
1 = Install from disk 


— Use Primary/Alternate PDT Bit 46 


0 = Use Primary Process Definition Template 
1 = Use Alternate Process Definition Template 


— Time/Date source Bit 47 


0 = Time/Date is accurate 
1 = Time/Date default value used 


Install Type Bin(2) 
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0 Normal IPL 
1 Manual Install 
2 = Automated Install 


Number of damaged main 
storage units 


National language index 
(Can be materialized and modified) 


Number of entries in object 
recovery list 


Tape sequence number for an AIPL 
Tape volume number for an AIPL 
Address of object recovery list 


Process control space created 
as the result of IPL or AIPL 


Queue Space object created 
as the result of an IPL or AIPL 


Reserved 


Console Information list 
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Bin(2) 


Bin(2) 


Bin(4) 


Bin(4) 
Bin(4) 
Space pointer 


system pointer 


system pointer 


Char(16) 
Char(400) 


(Array of five entries each 80 bytes in size) 


(1st=Primary, 2-5 =Reserved) 


— Console entry 
- Display LUD 
- Display CD 
- Controller model 
- Controller type 
- Controller serial number 
- Controller object data 
e Direct select address 
— lOP bus number 
— |IOP card, 
board structure 
- IOP card 
number 
- IOP board 
number 
e Logical bus address 
e IOP unit address 
e Resource Identifier 
e Reserved 
- Work station object data 
e Direct select address 
— {OP bus number 


— lOP card 

board structure 

- IOP card 

number 

- IOP board 

number 
e Logical bus address 
e Device unit address 
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Char(80) 
System pointer 
System pointer 
Char(4) 

Char(4) 

Char(4) 
Char(12) 
Char(2) 

Char(1) 

Char(1) 


Bits 0-3 
Bits 4-7 


Char(1) 
Char(2) 
Char(4) 
Char(3) 
Char(12) 
Char(2) 
Char(1) 


Char(1) 
Bits 0-3 
Bits 4-7 


Char(1) 
Char(2) 
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— Port Char(‘1) 
— Switch Setting Char(‘1) 
e Reserved Char(7) J 
- Device type Char(4) 
- Device model Char(4) 
- Flags Char(1) 
e information valid in entry Bit 0 
« Reserved Bit 1-7 
- Console keyboard type Char(1) 
- Console extended Char(1) 
keyboard type 
- Reserved Char(1) 
e Load/Dump Tape device Char(96) 


information list 
(Array of two entries each 48 bytes in size) 


(1st=LUD information, 2nd =CD information) 


— Load/Dump tape device entry Char(48) 
- Reserved Char(16) 
- LUD/CD information Char(12) 
e Direct select address Char(2) 
— lOP bus number Char(1) 
— |lOP card Char(1) 
board structure 
- |OP card Bits 0-3 
number i 
- IOP board Bits 4-7 wa 
number 
e Logical bus address Char(1) 
¢ Device unit address Char(2) 
e Flags Char(‘) 
— Information valid in Bit O 
entry 
— Reserved Bit 1-7 
e Reserved Char(6) 
- Device type Char(4) 
- Device model Char(4) 
- Reserved Char(12) 
e Recovery object list Char(*) 
(located by recovery object list pointer) 
— Recovery entry Char(32) 
(repeated for number of entries) 
- Object pointer System pointer 
- Object type Char(‘1) 
- Object status Char(15) 


Restart IMPL indicates that a Terminate Machine Processing instruction was issued with the 
restart option set to yes. The machine performed an IMPL without powering down the 
machine. 


Manual power on indicates the power switch on the operation panel was pressed to power > 
the system on. 
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Timed power on indicates the system was powered on using the system value specified by 
the customer. This option will only be honored when the Timed power on function is 
enabled. 


Remote power on indicates the system was power on by a phone call placed by the cus- 
tomer. This option will only be honored when the Remote power on function is enabled. 


Auto-power restart indicates the system was automatically powered on after a utility failure 
occurred and power was restored. This option will only be honored when the Auto-power 
restart function is enabled. 


UPS battery low indicates that a UPS battery is installed on the system and the battery is 
low. 


UPS bypass active indicates that the UPS has been bypassed. lf a utility power failure 
occurs, the UPS will not supply power. 


UPS power failed indicates that a utility failure has occurred and the system is currently 
running on battery power. 


UPS installed indicates that a Uninterrupted Power Supply is installed on the system and is 
available for use should the power fail. 


Operation Panel battery failure indicates the battery in the operation panel has failed and the 
system will not be able to determine the correct time and date upon the next IMPL. An 
approximate time and date will be given to the customer for verification. 


Operation Panel self test failed indicates the Operation Panel is possibly bad and some func- 
tion concerning the operation panel may not work correctly. 


Console status indicates whether the selected console is functioning normally or is inopera- 
tive. 


Console state indicates whether the selected console is ready to be used. 


Primary console status is set when the customer selected primary console is being used as 
the system console. 


ASCIll console status is set when a ASCII console is being used as the system console. 


Termination status indicates how the previous IMPL was terminated. If normal, the Termi- 
nate Machine Processing instruction successfully terminated the previous IMPL. If abnormal, 
the Terminate Machine Processing instruction did not successfully terminate the previous 
IMPL. This also implies that some cleanup of permanent objects may be required by the 
user. 


The duplicate user profile is valid only for AIPL and indicates if a user profile that is the 
same as the AIPL user profile to be created already exists in the machine context. The 
machine in this instance does not create the user profile for AIPL but rather uses the one 
located with the same name. 


Damaged AIPL user profile indicates if the currently existing user profile was detected as 
damaged and a new user profile was created as specified in the AIPL user profile creation 
template. 


Damaged machine context indicates if damage was detected in the machine context when an 
attempt was made to locate the duplicate user profile or to insert addressability to a newly 
created user profile. In either case, all current addressability is removed from the machine 
context, the new AIPL user profile is created, its addressability is inserted into the machine 
context, and the AIPL continues. Objects whose addressability was removed may have it 
reinserted using the Reclaim instruction for all objects or the Modify Addressability instruc- 
tion for a specific object. 


The object recovery list status field indicates that the status is complete unless one of the 
following conditions is true: 
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e The recovery list was lost. 
* More objects were to be placed in the list but there was insufficient space. 


The recovery phase completion field indicates that the status is complete unless one of the 
following conditions occurs: 


¢ An object to be recovered and/or inserted into the object recovery list no longer exists. 


e The objects to be recovered could not be determined due to loss of internal machine 
indicators that specified which objects were in use at machine termination. 


The most recent machine termination field is set to 0 unless all objects were not ensured at 
the most recent machine termination. 


The last MISR reset field is set to 0 if all objects were ensured at every machine termination 
since the MISR was last reset (to 0) using the Modify Machine Attributes instruction. 


IPL mode indicates which mode DST and the OS will be I[PLed. Either both will be attended 
or both will be unattended. 


Service Processor power on indicates if this is the first time the service processor card has 
been powered on. 


MISR Damage indicates if the machine detected that the MISR was damaged and it’s con- 
tents has to be reset to the default system values. 


Auto keylock position indicates if the keylock was is the auto position on the operation panel 
on the most recent IMPL. 


Normal keylock position indicates if the keylock was is the normal position on the operation 
panel on the most recent IMPL. 


Manual keylock position indicates if the keylock was is the manual position on the operation 
panel on the most recent IMPL. 


Secure keylock position indicates if the keylock was is the secure position on the operation 
panel on the most recent IMPL. 


Tower two present on 9404 system unit indicates if the system has second tower when the 
system is a 9404 system unit. 


Battery status for tower one on 9404 system unit indicates if a UPS battery is installed on the 


first tower of a 9404 system unit, the battery is low. 


Battery status for tower two on 9404 system unit indicates if a UPS battery is installed on the 


second tower of a 9404 system unit, the battery is low. 


Termination due to utility power failure and user specified delay time exceeded indicates the 


last termination of the system was due to a utility power failure and the system value speci- 
fied by the delay time had elapsed so the system was terminated. 


Termination due to utility power failure and battery low indicates the last termination of the 


system was due to a utility power failure and while running on battery power the voltage 
dropped below a level to continue to power the system so the system was terminated. 


Termination due to forced microcode completion indicates that the system when down by the 


user selecting power down from DST or the delayed power off switch was pressed on the 
operation panel. 

Auto power restart disabled due to a utility failure indicates the microcode disabled the auto 
power restart option when a condition was detected that would prevent the auto power 
restart to function properly. 


Reset utility power bits indicates that the power bits should be reset. This bit is only looked 
at when modifying the MISR. 
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Spread the operating system. indicates to spread the operating system on the next install 
instead of overlaying the existing objects. This bit is set to spread after a new dasd has 
been added. 


Install from Disk/Tape indicates when performing an install to use the initial OS/400 install 
program off of disk or to load the initial OS/400 install program off of tape. 


Primary/Alternate Process Definition Template indicates on IPL to initiate the initial OS/400 
process using the Primary or the Alternate Process Definition Template. 

Time/Date source informs OS/400 if the machine was able to determine the correct time/date 
or if it was forced to use the default time/date. 


Install type is set indicate whether an IPL or install was performed and if an install was per- 
formed, what type of install occurred. 


The number of damaged main storage transfer blocks field indicates the number of main 


storage transfer blocks that were detected as damaged by the machine during IMPL. 


National lanquage index is the value used to index to the the National language array kept 
by the system. 


The number of entries in the object recovery list field indicates how many objects are listed 
in the space located by the address of object recovery list field. 


The tape sequence number is set by the machine to allow the OS to perform their install. 
The tape volume number is set by the machine to allow the OS to perform their install. 


The address of object recovery list field contains a space pointer to the list of the potentially 
damaged objects that were identified during machine initialization. The number of such 
objects is indicated by the number of entries in the object recovery list field. 


The process control space created as a result of IPL _or AIPL is identified by a system pointer 


returned in this field. 


The Queue Space object pointer addresses the queue space object that was implicitly 
created by the machine for use by the inital process. This is created for both an IPL or an 
AIPL. During IPL or AIPL processing, before the queue space is created by the machine, the 
machine will attempt to destroy the queue space addressed by the MISR (this will be the 
queue space used on the previous IPL or AIPL). If the destroy fails (the MI user may have 
destroyed it sometime in the previous IPL), no error is reported and the IPL or AIPL proc- 
essing continues with the creation of the new queue space. The queue space is a perma- 
nent object, owned by the user profile used to initiate the initial process and is not 
addressed by a context. 


The console information list contains information for each console device as obtained from 
the Resource Configuration Record or set by the customer. 


The Load/Dump tape device information is information needed to build a Logical Unit 
Description and Controller Description object for the device used to install the operating 


system. 


The recovery object list identifies objects that required some activity performed on the 
object(s) during IPL. The list is located by the recovery object list pointer. 


Each entry in the list has the following general format: 


e Object system pointer 
¢ Object type Char(1) 
e Object status Char(15) 
— General status Char(2) 
- Damaged Bit O 
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0 = Object not damaged 
1 Object damaged 


- Reserved Bit 1 J 
- Suspended Bit 2 


0 Object not suspended 
1 = Object suspended 


Partially damaged Bit 3 


0 = Object not partially damaged 
1 = Object partially damaged 


- Journal synchronization Bit 4 


0 = Synchronization complete or not necessary 
1 = Synchronization failure 


- Reserved Bits 5-6 
- IPL detected damage Bit 7 


O = Any indicated damage was not detected by directory recovery 
1 = Indicated damage was detected by directory recovery 


- Reserved Bits 8-15 
Object specific status Char(13) 


(The format for the IPL recovery status for this portion of the object recovery list 
entries is different for each object type. A description of each follows by object 


type.) 


at 


Commit block status Char(2) aa 


Decommit Bit O 


0 = The journal has successfully been read backwards until either a start commit or 
a decommit entry was found. An attempt has been made to decommit all the 
data base changes but the attempt may not have been successful if the data 
space is damaged or if the function check flag is on. 

1 = The journal has not successfully been read backwards to a start commit or 
decommit entry and all the changes have not been decommitted. 


Journal read errors Bit 1 


O = No journal read errors 
1 = Journal read errors occurred during decommit 


Journal write errors Bit 2 


O = No journal write errors 
1 = Journal write errors occurred during decommit 


Partial damage to data space 


O = No partial damage encountered 
1 = Partial damage encountered on 1 or more data spaces 
Damage to data space Bit 4 


O = No damage encountered 
1 = Damage encountered on 1 or more data spaces oa 
Function check Bit 5 2 


O= No function check encountered 
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4= Function check encountered 
— Reserved Bit 6 
— Data space during IMPL Bit 7 


O= Data space is synchronized with the journal 
1= Data space is not synchronized with the journal. All changes may not be decom- 
mitted. 


— Decommit reason code Bits 8-10 


000 Decommit not performed 

001 = Decommit at IPL 

010 = Process termination 

100 = Decommit instruction (all other values reserved) 


— System initiated MI DECOMMIT Bit 11 


O= Operating system did not initiate the decommit 
1= Operating system did initiate the decommit 


— Reserved Bits 12-15 
— Reserved (binary 0) Char(7) 
— Start commit journal Bin(4) 


— Sequence number 


Data space . 
— Status Char(13) 
- Indexes detached from Bit O 
data space 
O = Indexes remain attached 
1 = All indexes detached from this data space 
Reserved (binary 0) Bits 1-15 
— Reserved (binary 0) Char(7) 
— Ordinal entry number of Bin(4) 
last entry 
Data space index 
— Status Char(13) 
- Invalidated Bit O 


0 = Not invalidated 
1 = Invalidated 


- Recovered by journal Bit 1 


O = Not recovered 
1 = Recovered 


- Reserved (binary Q) Bits 2-15 
.Reserved (binary 0) Char(11) 
Journal port 
— Status Char(13) 
- Synchronization status Bit 0 


0 = All objects synchronized 
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1 = Not all objects synchronized 


- Reserved Bits 1-7 
— Reserved Char(10) 
— Number of journal spaces Bin(2) 
attached 


e Journal space 


— Status Char(13) 
- Journal space usable Bit 0 
QO = Journal space is usable 
1 = Journal space is not usable 
- Threshold reached Bit 1 


O= Threshold has not been reached 
1= Threshold has been reached 


Reserved Bits 2-7 
— Reserved Char(4) 
— First journal sequence number Bin(4) 
— Last journal sequence number Bin(4) 


All objects-Any damage detected during IPL is reported in the general status information. If 
this damage is detected as a result of special processing performed during directory rebuild, 
it is indicated in the IPL detected damage field. A journal synchronization failure indicates 
the designated object was not made current with respect to the journal. Subsequent 
attempts to apply journal changes from the journal to this object will not be allowed. 


Commit block-All commit blocks that were attached to an active process during the previous 
IPL are interrogated at the following IPL. The system attempts to decommit any uncom- 
mitted changes referenced through these commit blocks. The results of this attempted 
decommit is reported in the status field. The system also returns the journal entry sequence 
number of the start commit journal entry (hex 0500) last created for this commit block if there 
were any uncommitted changes. If the number is not returned, a value of binary zero is 
returned. 


Data space-lf object damage was detected during IPL, the object is marked as damaged, 
damage is indicated in the object status field, and an event is signaled. In this case, the 
highest ordinal entry number is 0. In certain situations, the data space indexes over the 
data space become detached and therefore must be recreated. If the object is not damaged, 
the data space is usable and the highest ordinal entry number is set. The ordinal entry 
number of last entry indicates the last entry in the data space. Updates are not guaranteed. 
Updates may be out of sequence or partially applied and must be verified by the user for 
correctness. 


Data space index-lf object damage was detected during IPL, the object is marked as 
damaged, damage is indicated in the object status field, and an event is signaled. If the 
object was invalidated because changes were made in a data space addressed by the data 
space index, the data space index is included in the list and marked as invalidated. The 
ASP number of the data space index is indicated in the list. The associated data space is 
also included elsewhere in the object recovery list. Only damaged or invalidated data space 
indexes are included in the list. 


Journal port-Each journal port in the system is interrogated at IPL. The status field contains 
the result of this checking and also the result of the attempt to synchronize the objects (if 
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necessary) being journaled through the indicated journal port. A default journal port is spec- 
ified when created. and indicates the port is to be used by the machine in implicitly jour- 
naling objects. The system also returns the number of journal spaces attached to the 
journal port after IPL is complete. 


Journal space-Each journal space that was attached to a journal port or used by the system 
to synchronize an object which was being journaled at the time of the previous machine ter- 
mination is interrogated during IPL. The status field reports the results of this interrogation 
and synchronization use. Journal spaces are referenced by the object recovery list if this 
IPL was preceded by an abnormal failure, some unexpected condition was discovered during 
the IPL, or the journal space is a default journal space. The first journal sequence number 
on the journal space is returned. The last usable entry on the journal space is also identi- 
fied. If the journal space is damaged, these fields will contain zeroes. 


Uninterruptible power supply delay time and calculated delay time. Note: The UPS delay 
time is meaningful only if a UPS is installed. 


The format of the template for the uninterruptible power supply delay time (including the 
8-byte prefix) is as follows: 


¢ Number of bytes available Bin(4) 
¢ Number of bytes provided Bin(4) 
e UPS Delay time Bin(4) 
¢ Calculated UPS Delay time Bin(4) 


The delay time interval is the amount of time the system waits for the return of utility 
power. lf a utility power failure occurs, the system will continue operating on the UPS 
supplied power. If utility power does not return within the user specified delay time, the 
system will perform a quick power down. The delay time interval is set by the customer. 
The calculated delay time is determined by the amount of main storage and DASD that 
exists on the system. Both values are in seconds. 


The VPD (vital product data) is a template that contains information for memory card VPD, 
processor VPD, columbia/Colomis VPD, central electronic complex (CEC) VPD and the panel 
VPD. | 


The materialize format of the VPD (Including the 8-byte prefix) is as follows: 


re ee ee 


e Number of bytes available Bin(4) 
e Number of bytes provided Bin(4) 

e Reserved Char(8) 
e System VPD location Char(48) 
— Offset to memory VPD Bin(4) 

— Offset to Processor VPD Bin(4) 

— Offset to Columbia/Colomis Bin(4) 
— Offset to CEC VPD Bin(4) 

— Offset to Panel VPD Bin(4) 

— Reserved Char(28) 

e Main store memory VPD Char(1040) 

— Usable memory installed Bin(2) 


(In megabytes) 
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— Minimum memory required Bin(2) 
(In megabytes) 
Se Reserved Char(12) 
— Memory array Char(1024) 
(An array of 16, 64-byte entries) . 
- Memory status Char(2) 
e Memory card status Bit(2) 
e Invalid memory card Bit 0 
e Unrecognized card Bit 1 
e Memory not supported Bit 2 
¢ Card/model mismatch Bit 3 
¢ Interface error Bit 4 
¢ Refresh error Bit 5 
e Addressing error Bit 6 
e 1st Nonterminating FRU Bit 7 
e 2nd Nonterminating FRU Bit 8 
e 3rd Nonterminating FRU _Bit 9 
e Reserved Bits 10-15 
- Memory card size Bin(2) 
(In megabytes) 
- Number of CCINS for this card Char(1) 
- Array of CCINS for this card Char(32) 
(Array of 8, 4-byte entries) 

- Physical slot # of this card Char(‘1) 

- Reserved Char(26) 
Processor VPD Char(1280) 
(An array of 16, 80-byte entries) 

— Processor status Char(4) 

- Processor card status Bits 0-1 

- Reserved Bits 2-31 
— Processor CCIN number Char(4) 
— Processor model number Char(4) 
— Processor part number Char(12) 
— Processor serial number Char(4) 
— Processor manufacturing ID Char(4) 
— Processor load identifier Char(4) 
— Reserved CHAR(44) 
Columbia/Colomis VPD Char(32) 
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(An array of 2, 64-byte entries) 


(ist entry is Columbia, 2nd is Colomis) 


— Card status Char(4) 
- Card usability status Bits 0-1 
- Reserved Bits 2-31 
— Card CCIN number Char(4) 
— Card model number Char(4) 
— Card part number Char(12) 
— Card serial number Char(4) 
— Card manufacturing ID Char(4) 
— Reserved Char(32) 
CEC VPD Char(32) 
— Status of last CEC read Char(4) 
— System manufacturing !D Char(4) 
— System serial number Char(4) 
— System type Char(4) 
— System model number _ Char(4) 
— Pseudo model number | Char(4) 
— System Password Char(8) 
Panel VPD Char(64) 
— Panel VPD entry status Char(2) 
- Panel VPD is usable Bit O 
- Reserved Bits 1-15 
— Panel type Char(4) 
— Panel model number Char(3) 
— Panel part number Char(12) 
— Panel serial number Char(4) 
— Panel manufacturing ID Char(4) 
— Alterable ROS part number Char(12) 
— Alterable ROS card number Char(10) 
— Alterable ROS ID Char(1) 
— Alterable ROS flag Char(‘1) 
— Alterable ROS fix ID Char(1) 
— Reserved Char(10) 


Materialize Machine Attributes (MATMATR) 


The system VPD location information is used to determine where each of the separate VPD 
sections start relative to the beginning of the VPD materialization template. 


The usable memory installed field contains the amount of memory (in megabytes) which the 
system recognizes as being valid. 
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The minimum memory required field contains the amount of memory (in megabytes) which is 
required for the system to run at optimum performance. 


The remainder of the memory VPD is an array of 16, 64 byte entries which contains specific 
information about each memory card installed on the system. The memory card status field 
should be interpreted in the following way: 


e 0O = Memory card usable, no failures 
¢ 01 = Memory card usable, but has failures 
e 10 = Memory card is not installed 


« 11 = Memory card is not usable due to critical failure 


The remaining status bits will have a value of 1 if the condition is true or a value of 0 if the 
condition is not true. 


The memory card size is a two byte field which will contain the number of megabytes of 
main store this card represents. 


The number of CCINs field for this card contains a count of the number of CCINs which were 
found for this card. This number should be used to determine how many CCIN entries follow 
in the array of CCINs for this card field. This is a 32 byte field which is divided into 8, 4-byte 
entries. Each entry contains a CCIN number for this memory card. 


The Processor VPD is an array of 16 entries, each 80 bytes in length. Each entry corre- 
sponds to a processor card. To determine the status of a processor card, the processor 
card status field should be interpreted in the following way: 


e 00 = Processor usable, no failures 
e Q1 = Processor usable, but has failures 
e 10 = Processor is not installed 


e 11 = Processor is not usable due to critical failure 


The Columbia/Colomis VPD is an array of 2 entries, each 64 bytes in length. The first entry 
contains information concerning the Columbia card, the second entry contains information 
concerning the Colomis card. To determine the status of either card, the status field should 
be interpreted in the following way: 


¢ 00 = Card usable, no failures 

* 01 = Card usable, but has failures 
e 10 
e 11 


The Panel VPD may or may not be filled in on a particular system depending upon what type 
of panel is installed, to determine if the panel VPD information is valid, the panel VPD usable 
bit must be 1. If this field is 0, the panel VPD information is not valid. 


Network Attributes 
(can be materialized and modified) 
(only allowed in attribute selection value) 


Card is not installed 


Card is not usable due to critical failure 


The Network Attributes is a template that contains information concerning APPN network 
attributes. 


The materialize format of the Network attributes is as follows: 


e Network Data Char(190) 
— System name Char(8) 
— System name length Bin(2) 
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New System name Char(8) 
New system name length Bin(2) 
Local system network identification Char(8) 
Local system network identification length Bin(2) 
End node data compression Bin(4) 
Intermediate node data compression Bin(4) 
Reserved Char(2) 
Local system control point name Char(8) 
Local system control point name length Bin(2) 
Reserved Char(10) 
Default local location name Char(8) 
Default local location name length Bin(2) 
Default mode name Char(8) 
Default mode name length Bin(2) 
Maximum number of intermediate sessions Bin(2) 
Maximum number of conversations per APPN LUD Bin(2) 
Local system node type Char(1) 
Reserved -Char(1) 
Route addition resistance Bin(2) 
List of network server network |D’s Char(40) 
(An array of five entries each 8 bytes in size) 
List of network server network ID lengths Char(10) 
(An array of five entries each 2 bytes in size) 
List of network server control point names Char(40) 
(An array of five entries each 8 bytes in size) 
List of network server control point name lengths Char(10) 
(An array of five entries each 2 bytes in size) 
Alert flags Char(1) 

- Alert priority focal point Bit 0 

- Alert default focal point Bits 1-7 

- Reserved Bit(6) 
Network Attribute Flags Char(1) 
(Materializable only) 

- Network attributes Bit 0 initialized 


- Pending system name 
system name 


- Reserved 


Bits 1 made current 


Bit(2-7) 


The machine system name is defaulted to the system serial number with a ’S’ in the first 
position. Thereafter, it may be modified to any value of 1 through 8 characters with the first 


character alphabetic. 
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The machine system name length is kept to determine how long the system name is. The 
default value for the length is eight. 


The new system name is a tentative new value chosen for the machine system name. This 
value will become the machine system name at the next IPL. The initial value is null and the 
syntax rules are the same as those for the machine system name. 


The new system name length is kept to determine how long the new system name is. The 
default value for the length is zero. 


The local system network identification default is “APPN’ and the default local system 
network identification length is four. 

The end node data compression field controls whether the machine will allow data com- 
pression when it’s an end node. This value is used when the mode description is equal to 
“NETATR. If one of the values listed in the table below is not specifed, then the value speci- 
fied is equal to the maximum line speed that data should be compressed. Any configuration 
with a line speed slower than what is specified here will cause the data to be compressed. 
Valid values range from 1 bits-per-second through 2147483647. 


O = *NONE (default) 
No data compression will be done. 
-1 = *REQUEST 
Data compression is requested on the session. 
-2 = *ALLOW 
Data compression is allowed, but not requested for this session. 
-3 = “REQUIRE 
Data compression is required on this session. 


The intermediate node data compression field controls whether data compression will be 
requested by the machine when it’s an intermediate node. This value is used when the 
mode description is equal to *“NETATR. If one of the values listed in the table below is not 
specifed, then the value specified is equal to the maximum line speed that data should be 
compressed. Any configuration with a line speed slower than what is specified here will 
cause the data to be compressed. Valid values range from 1 bits-per-second through 
2147483647. 


O = *NONE (default) 
No data compression will be done. 
-1 = *REQUEST 
Data compression is requested on the session. 


The local system control point name default is the system serial number with a character ’S’ 
in the first position and the default control point name length is eight. 


The local location name default is the system serial number with a character ’S’ in the first 
position and the default local location name length is eight. 


The mode name default is all blanks and the default mode length is eight. 


The maximum number of intermediate sessions default is 200. 


The maximum number of conversations per APPN LUD is 64. 
The local system node type default is hex 01. 
The route addition resistance default is 128. 


All entries of the network server network IDs are defaulted to blanks with all entries of the 
network server network IDs lengths defaulting to zero. 

All entries of the network server control point names are defaulted to blanks with all entries 
of the network server control point name lengths defaulting to zero. 
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Date Format 


The date format is the format is which the date will be presented to the customer. The pos- 
sible values are YMD. MDY, DMY. JUL where Y = Year, M = Month, D = Day and JUL = 
Julian. 


The format of the template for date format is as follows: 


* Number of bytes available Bin(4) 
* Number of bytes provided Bin(4) 
« Date Format Char(3) 


Leap Year Adjustment 


The leap year adjustment is added to the leap year calculations to determine the year in 
which the leap should occur. The valid values are 0, 1, 2, 3. 


The format of the template for leap year adjustment is as follows: 


e Number of bytes available Bin(4) 
e Number of bytes provided Bin(4) 
e Leap year adjustment Bin(2) 


Hex 013C Timed Power On 


Hex 0140 


Hex 0144 


The timed power on is the time and date at which the system should automatically power on 
if it is not already powered on. 


The format of the template for timed power on is as follows: 


¢ Number of bytes available Bin(4) 
e Number of bytes provided Bin(4) 
e Minute Bin(2) 
e Hour Bin(2) 
¢ Day Bin(2) 
¢ Month Bin(2) 
e Year Bin(2) 


Timed Power On Enablie/Disable 


The timed power on enable/disable allows the timed power on function to be queried to 
determined if the function is enabled or disabled. 


The format of the template for timed power on enable/disable is as follows: 


¢ Number of bytes available Bin(4) 
¢ Number of bytes provided Bin(4) 
¢ Enable/Disable Bin(2) 


Hex 8000-indicates timed power on is enabled 
Hex 0000-indicates timed power on is disabled 
Remote Power On Enable/Disable 


The remote power on enable/disable allows the remote power on function to be queried to 
determined if the function is enabled or disabled. 


The format of the template for remote power on enable/disable is as follows: 


¢ Number of bytes available Bin(4) 
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e Number of bytes provided Bin(4) 
¢ Enable/Disable Bin(2) 
Hex 8000-indicates remote power on is enabled J 


Hex 0000-indicates remote power on is disabled 
Auto power restart Enable/Disable 


The auto power restart enable/disable allows the auto power restart function to be queried 
to determined if the function is enabled or disabled. 


The format of the template for auto power restart enable/disable is as follows: 


¢ Number of bytes available Bin(4) 
¢ Number of bytes provided Bin(4) 
¢ Enable/Disable Bin(2) 


Hex 8000-indicates auto power restart is enabled 


Hex 0000-indicates auto power restart is disabled 


Hex 014C Date separator 


Hex 0164 


Hex 0168 


The date separator is used when the date is presented to the customer. The valid values 
are a slash(/), dash(-), period(.), comma(,) and a blank( ). 


The format of the template for the date separator is as follows: 


e Number of bytes available ‘Bin(4) 
e Number of bytes provided Bin(4) 
¢ Date Separator Char(1) 2 


Uninterruptible power supply type 
Note: The UPS type is meaningful only if a UPS is installed. 


The uninterruptible power supply type option allows the MI user to tell the machine how 
much of the system is powered by a UPS (ie, what type of UPS is installed). A full UPS will 
power all racks in the system. A mini UPS will power the racks containing the CEC and the 
load source. 


The format of the template for UPS Type is as follows: 


¢ Number of bytes available Bin(4) 
« Number of bytes provided Bin(4) 
¢ UPS Type Bin(2) 


Hex 0000-indicates a full UPS is installed (all racks have a UPS installed) 
Hex 8000-indicates a mini UPS is installed (only the minimum number of racks are 
powered) 
Panel Status Request 
The Panel Status Request option allows BOSS to determine what current status of the oper- 
ations panel. 
The format of the template for Panel Status Request is as follows (including the usual 8-byte 
prefix): 


« Number of bytes available Bin(4) . 
« Number of bytes provided Bin(4) 2 
¢ Current IPL type Char(1) 
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Uninterrupted power supply 
installed 


O = UPS not installed 
1 = UPS installed, ready for use 


Utility power failed, 
running on UPS 


QO = Running on utility power 
1 Running on UPS 


Uninterrupted power supply 
(UPS) bypass active 


0 
1 


UPS bypass not active 
UPS bypass active 


Uninterrupted power supply 
(UPS) battery low 


0 = UPS battery not low 
1 = UPS battery low 


Auto keylock position 


0 
1 


Normal keylock position 


Keylock not in auto position 
Keylock in auto position 


0 = Keylock not in normal position 
1 = Keylock in normal position 


Manual keylock position 


0 
1 


Secure keylock position 


Keylock not in manual position 
Keylock in manual position 


0 = Keylock not in secure position 
1 = Keylock in secure position 


Reserved 


Reserved 


Most recent IPL type 


The current IPL type is the state of the IPL type at the operations panel. Possible values are 
A, B, C, D. 


UPS installed indicates that a Uninterrupted Power Supply is installed on the system and is 
available for use should the power fail. 
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Char(2) 
Bit 0 


Bit 1 


Bit 2 


Bit 3 


Bit 4 
‘Bit 5 
Bit 6 
Bit 7 


Bits 8-15 
Char(5) 
Char(1) 


UPS power failed indicates that a utility failure has occurred and the system is currently. 
running on battery power. 


UPS bypass active indicates that the UPS has been bypassed. lf a utility power failure 


occurs, the UPS will not supply power. 


UPS battery low indicates that a UPS battery is installed on the system and the battery is 


low. 


Auto keylock position indicates that the keylock is currently in the auto position on the oper- 
ation panel. 
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Normal keylock position indicates that the keylock is currently in the normal position on the 
operation panel. 


Manual keylock position indicates that the keylock is currently in the manual position on the 
operation panel. 


secure keylock position indicates that the keylock is currently in the secure position on the 
operation panel. 


The most recent IPL type is the type of IPL that was performed on the most recent IPL. Pos- 
sible values are A, B, C, D. 


Hex 016C Extended machine initialization status record 


The XMISR (extended machine initialization status record) is used to report the status of the 
machine. 


The materialize format of the XMISR is as follows: 


Number of bytes available 
Number of bytes provided 
Save storage status 

— Checksumming status 


0 = Checksumming was not stopped 
1 = Checksumming was stopped 


— Completion status 


0 = Save storage did not complete 
1 = Save storage completed 


— System restored status 


O = Save storage did not restore the system 
1 = Save storage restored the system 


— Save storage attempted 


0 = Save storage not attempted 
1 = Save storage was attempted 


— Unreadable sectors 


O = Unreadable sectors were not found 
1 = Unreadable sectors were found during save operation 


— Check for active files on 
save storage media 


0 = Do not check for active files on save storage media 
1 = Check for active files on save storage media 


— Reserved 
Save storage information 


— Tape device information 
- Number of tape device 
entries 


e Tape device address 
e (Array of four entries, each 4 bytes in size) 


— Tape device |OP 
address 


Bin(4) 
Bin(4) 
Char(4) 
Bit O 


Bit 1 


Bit 2 


Bit 3 


Bit 4 


Bit 5 


Bits 6-31 
Char(118) 


Char(18) 
UBin(2) 


Char(16) 


Char(2) 
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— Tape device Char(2) 
device address 
- ‘Tape volume names Char(62) 
structure 
¢ Number of tape UBin(2) 
volume entries 
« Tape volume names Char(60) 
e (Array of ten entries, each 6 bytes in size) 
- Tape expiration date Char(6) 
- Bad sector count Char(4) 
- Date from save tape Char(6) 
- Time last successful Char(8) 
save started 
- Reserved Char(14) 
e Install tape Volume ID Char(6) 
¢ IPL sequence number ID Bin(4) 
e« Physical address of tape device used Char(4) 


for last D-type |PL 
Alternate initial process definition template 


The alternate initial process definition template is used by the machine when performing an 
automated install. 


No check is made and no exception is signaled if the values in the template are invalid; 
however, the next automated install will not be successful. 


Hardware storage protection state 
Note: Hardware storage protection is meaningful only on version 2 hardware or later. 


The hardware storage protection state indicates if the machine will honor the protection 
state of objects on the system. When it is active, references by user state programs to pro- 
tected objects will result in object access denied (hex 4401) exceptions. When hardware 
storage protection is inactive, or when running on version 1 hardware, accesses of protected 
objects by user state programs will go undetected. 


The format of the template for hardware storage protection state option is as follows 
(including the usual 8-byte prefix): 


¢ Number of bytes available Bin(4) 
¢ Number of bytes provided Bin(4) 
e Hardware storage protection state Bin(2) 


Hex 0000-indicates hardware storage protection is inactive 
Hex 8000-indicates hardware storage protection is active 


Time separator 


The time separator is used when the time is presented to the customer. The valid values 
are a colon(:), period(.), commaj(,) and a blank{ ). 


The format of the template for the time separator is as follows: 


¢ Number of bytes available Bin(4) 
¢ Number of bytes provided Bin(4) 
¢ Time separator Char(1) 
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Materialize Machine Attributes (MATMATR) 


Hex 0184 Software Error Logging 


The software error logging machine attribute is used to allow the MI user to determine 


whether or not software error logging is active for the machine J 
The format of the template for software error logging is as follows: 

* Number of bytes available Bin(4) 

« Number of bytes provided Bin(4) 

e Software error logging Bin(2) 


Hex 8000-indicates software error logging is active 
Hex Q000-indicates software error logging is not active 


Hex 0188 Machine task termination event control option 
(can be materialized and modified). 


The machine task termination event option controls if the machine will signal a machine 
wide event when machine tasks terminate. The default, which is established every IPL, is to 
not signal machine task termination events. The machine task termination event id is hex 
0016,05,01. 


The format of the template for the machine task termination event option is as follows: 


* Number of bytes available Bin(4) 
e Number of bytes provided Bin(4) 
e VLIC task termination event option ‘Bin(2) 


Hex 8000-indicates machine task termination events will be signaled. 


Hex 0000-indicates machine task terminations events will not be signaled. >’ 


Limitations: Data-pointer-defined scalars are not allowed as a primary operand for this instruction. 
An invalid operand type exception is signaled if this occurs. 


Exceptions 
Operands 
Exception 1 2 Other 
06 Addressing 
01 space addressing violation X X 
02 boundary alignment X X 
03 range X X 
06 optimized addressability invalid X X 
10 Damage encountered 
04 system object damage state X X 
44 partial system object damage X X X 
1C Machine-dependent exception 
03 machine storage limit exceeded X 
0A service processor unable to process request X 
20 Machine support | 
02 machine check X ) 


03 function check 
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Exception 


22 


24 


2E 


32 


36 


38 


Object access 

01 object not found 

02 object destroyed 
03 object suspended 


08 object compressed 


Pointer specification 
01 pointer does not exist 


02 pointer type invalid 


Resource control limit 


01 user profile storage limit exceeded 


Scalar specification 
01 scalar type invalid 
02 scalar attributes invalid 


03 scalar value invalid 


Space management 


01 space extension/truncation 


Template specification 


03 materialization length exception 


Materialize Machine Attributes (MATMATR) 


Operands 
1 2 
Xx X 
X X 
X X 
X X 
xX X 
X X 

X 

X 
x 


Other 
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Materialize Machine Data (MATMDATA) 


Op Code (Hex) Operand 1 Operand 2 
0522 Receiver Materialization 
options 


Operand 7: Character variable scalar (fixed length) 


Operand 2: Character(2) or unsigned binary(2) scalar or immediate (fixed length) 


ILE access 


MATMDATA ( 
receiver : space pointer; 
materialization options : aggregate 


) 
OR 


MATTOD ( 
var time_of day : aggregate 


Description: This instruction makes available the unique values of machine data. The values of 
various machine data are placed in the receiver. 


Operand 2 is a 2-byte value. The value of operand 2 determines which machine data are materialized. 
Operand 2 is restricted to a constant character or unsigned binary scalar or an immediate value. 


e Materialization options Char(2) 


Hex 0000 = Materialize time of day clock 
Hex 0001 = Materialize system parameter integrity validation flag 
Hex 0002 through FFFF Reserved 


Operand 1 specifies a receiver into which the materialized data is placed. It must specify a character 
scalar with a minimum /Jength which is dependent upon the materialization option specified for operand 
2. The reciever may be substringed. The start position of the substring may be a variable. However, 
the length of the substring must be an immediate or constant. If the length specified for operand 1 is 
less than the required minimum, an exception is signaled. Only the bytes up to the required minimum 
length are used. Any excess bytes are ignored. 


The data placed into the receiver differs depending upon the materialization option specified. The fol- 
lowing descriptions detail the formats of the optional materializations. 


« Hex 0000 = Materialize time of day clock 
minimum receiver length is 8 


Time-of-day clock Char(8) 


The time-of-day clock provides a consistent measure of elapsed time. The maximum elapsed time 
the clock can indicate is approximately 143 years. 


The time-of-day clock is a 64-bit unsigned binary counter with the following format: 
Oh oactocovoiletcs 41 42 reserved 63 


The bit positions of the clock are numbered from 0 to 63. 
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Materialize Machine Data (MATMDATA) 


The clock is incremented by adding a 1 in bit position 41 every 1024 microseconds. Bit positions 42 
through 63 are used by the machine and have no special meaning to the user. Note that these bits 
(42-63) may contain either binary 1’s or binary 0’s. 


Unpredictable results occur if the time of day is materialized before it is set. 


The maximum unsigned binary value that the time of day clock can be modified to contain is hex 
DEFEFFRRFERREFEE. 


* Hex 0001 = Materialize system parameter integrity validation flag 
minimum receiver length is 1 


system parameter integrity validation flag Char(1) 


This option returns the value of the machine attribute which specifies whether additional validation 
of parameters passed to programs which run when the process is in system state is to be per- 
formed, such as for U. S. government’s Department of Defense security ratings. 


A value of hex 01 indicates this additional checking is being performed. A value of hex 00 is 
returned otherwise. 


Performance note: The time of day clock and the system parameter integrity validation flag may be 
materialized both with this instruction and also with the Materialize Machine Attributes instruction. 
The performance of this instruction is considerably better. 


Exceptions 
Operands 

Exception 1 2 Other 
06 Addressing 

01 space addressing violation X 

02 boundary alignment X 

03 range X 

06 optimized addressability invalid X 
08 Argument/parameter 

01 parameter reference violation X 
10 Damage encountered 

04 system object damage state xX 

44 partial system object damage X 
1c Machine-dependent exception 

03 machine storage limit exceeded xX 
20 Machine support 

02 machine check X 

03 function check X 
22 Object access 

01 object not found X 

02 object destroyed xX 

03 object suspended X 
24 Pointer specification 

01 pointer does not exist X 
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Materialize Machine Data (MATMDATA) 


Operands 

Exception 1 2 Other 

02 pointer type invalid X ) 
2E Resource control limit 

01 user profile storage limit exceeded X 
32 Scalar specification 

01 scalar type invalid X X 

02 scalar attributes invalid X X 

03 scalar value invalid X 
36 Space management 

01 space extension/truncation X 
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Exception Specifications 


Chapter 23. Exception Specifications 


This chapter describes the exceptions which can be signaled by the machine. Exception generation is 
the only facility for synchronously communicating error conditions that are a direct result of AS/400 
instruction processing. Machine exceptions identify error conditions that require processing before the 
next sequential AS/400 instruction is executed. Instructions that cause a particular exception may not 
function identically before execution is stopped; however, each instruction produces consistent results. 
These results ensure machine integrity and reliability. The results are inherent in a particular excep- 
tion definition or in the detailed instruction definition. 


The user can monitor any number of exceptions. There are three basic techniques for the user to 
handle an exception. One technique is to provide detailed handling specified by a program defined 
exception description object. The second technique is to provide a default exception handler for the 
process. This exception handler is invoked whenever an invocation fails to handle an exception. The 
third technique is to accept the machine default of process termination by not providing an appropriate 
exception handling mechanism. 
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Exception Specifications 


Machine Interface Exception Data 


Exception data is communicated across the machine interface through a Retrieve Exception Data 
instruction. Certain information is available for all exceptions when an appropriate exception 
description has been defined by the user. That information includes the following: 


« Exception identification-This is a 2-byte hexadecimal field formed by concatenating to the high- 
order 1-byte exception group number a low-order 1-byte exception subtype number. The format of 
the exception identification is as follows: 


1 2 3 4 
Subtype 
Number 

Group 

Number 


e Compare value length 

« Compare value (machine signaled have a compare value of hex 00000000 with a length of 4) 
« Exception-specific data 

*« Signaling program invocation address 

e Signaled program invocation address 

e Signaling program instruction address 

e Signaled program instruction address 

e Machine-dependent data identifying the component that generated the exception 


The exception-specific data provides additional pointers and data that may be required for an indi- 
vidual exception. 
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Exception List 


The following is a list of all exceptions in alphabetic and numeric order by group. The subtypes within 
each group are in numeric order. 


02 


04 


06 


08 


OA 


0c 


Access Group 


01 


Object ineligible for access group 


Access State 


01 Access state specification invalid 
Addressing 

01 Space addressing violation 

02 Boundary alignment 

03 Range 

04 External data object not found 

05 Invalid space reference 

06 Optimized addressability invalid 
Argument/Parameter 

01 Parameter reference violation 

02 Argument list length violation 

03 Argument list length modification violation 


Authorization 


01 
02 
03 
04 
05 
06 


Unauthorized for operation 

Privileged instruction 

Attempt to grant/retract authority state to an object that is not authorized 
Special authorization required 

Create/modify user profile beyond level of authorization 


Grant/retract authority invalid. 


Computation 


01 

02 
03 
04 
05 
06 

07 
08 

09 
OA 
0B 
OC 


Conversion 

Decimal data 

Decimal point alignment 
Edit digit count 

Edit mask syntax 
Floating-point overflow 
Floating-point underflow 
Length conformance 
Floating-point invalid operand 
size 

Zero divide 


Invalid floating-point conversion 
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OE 


10 


12 


19 


Exception Specifications 


Floating-point inexact result 
Floating-point zero divide 
Master key not defined 

Weak key not valid 

Key parity invalid 

Invalid extended character data 
Invalid extended character operation 
Invalid compressed data 

Date boundary overflow 

Date format error 

Date value error 

Date boundary underflow 


Space pointer operands do not point to the same space object 


Context Operation 


01 
02 


Duplicate object identification 


Object ineligible for context 


Damage Encountered 


02 
04 
05 
44 
Data 
01 
02 
03 
04 
05 
06 
07 
08 
09 
0A 
OB 


Machine context damage state 

System object damage state 

Authority verification terminated due to damaged object 
Partial system object damage state 

Base Management 

Conversion mapping error 

Key mapping error 

Cursor not set 

Data space entry limit exceeded 

Data space entry already locked 

Data space entry not found 

Data space index invalid 

Incomplete key description 

Duplicate key value in existing data space entry 

End of path 

Duplicate key value detected while building unique data space index 
No entries locked 

Duplicate key value in uncommitted data space entry 
Invalid mapping template 

Invalid selection template 


Data space not addressed by index 
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16 


18 


1A 


16 
17 
18 
19 
1A 
1B 
1C 
1D 
21 
25 
26 
27 
30 
32 
33 
34 
36 
37 
38 
39 
40 
41 
42 
43 
62 


Exception Specifications 


Data space not addressed by cursor 

Key changed since set cursor 

Invalid key value modification 

Invalid rule option 

Data space entry size exceeded 

Logical space entry size limit exceeded 

Key size limit exceeded 

Logical key size limit exceeded 

Unable to maintain a unique key data space index 

Invalid data base operation 

Data space index with invalid floating-point field build termination 
Data space index key with invalid floating-point field 
Specified data space entry rejected 

Join value changed 

Data space index with non-user exit selection routine build termination 
Non-user exit selection routine failure 

No mapping code specified 

Operation not valid with join cursor 

Derived field operation error 

Derived field operation error during build index 

Invalid entry definition table 

ISV parameter value in runtime data pointer array not correct 
Unique fanout join failed 

DDAT had an error 


Parent index cannot be used to create new index 


Exception Management 


01 
02 
03 
04 
05 


Exception description status invalid 
Exception state of process invalid 
Invalid invocation address 
Resume/retry invalid 


No inquiry message found for reply message 


Independent Index 


01 


Duplicate key argument in index 


Lock State 


01 
02 
03 
04 


Invalid lock state 
Lock request not grantable 
Invalid unlock request 


Invalid object lock transfer request 
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1E 


20 


22 


24 


26 


05 Invalid space location unlock 
Machine-Dependent Exception 

01 Machine-dependent request invalid 
02 Program limitation exceeded 

03 Machine storage limit exceeded 

04 Object storage limit exceeded 

06 Lock limit exceeded 

O07 Modify main storage pool controls invalid 
08 Requested function not valid 

09 Auxiliary storage pool number invalid 
OA Service Processor unable to process request 
Machine Observation 

01 Program not observable 

02 Invocation not found 

03 Machine storage limit exceeded 

04 DBGINT error 

05 DBGINT error 

Machine Support 

01 Diagnose 

02 Machine check 

03 Function check 

Object Access 

01 Object not found 

02 Object destroyed 

03 Object suspended 

04 Object not eligible for operation 

05 Object not available to process 

06 Object not eligible for destruction 

07 Authority verification terminated due to destroyed object 
08 Object Compressed 

OA Program not eligible for operation 
Pointer Specification 

01 Pointer does not exist 

02 Pointer type invalid 

03 Pointer addressing invalid object 

04 Pointer not resolved 

Process Management 

02 Queue full 


Exception Specifications 
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2A 


Process State 


01 
02 
OA 


Process ineligible for operation 
Process control space not associated with a process 


Process attribute modification invalid 


Program Creation 


01 
02 
03 
04 
05 
06 
07 
08 
09 
OA 
0B 
0C 
OD 
10 
11 
12 
14 
15 
16 
17 
18 
19 
1A 
1B 
1C 
1D 
1E 
1F 
20 
21 
SE 
oF 
60 


Program header invalid 

ODT syntax error 

ODT relational error 

Operation code invalid 

Invalid op code extender field 

Invalid operand type 

Invalid operand attribute 

Invalid operand value range 

Invalid branch target operand 

Invalid operand length 

Invalid number of operands 

Invalid operand ODT reference 

Reserved bits are not zero 

Automatic storage for procedure exceeds maximum 
Machine automatic storage exceeds maximum 
Data type or length of initial value not valid 

static data initialized to address of automatic data 
Initial value for static data not valid 

Number of procedures exceeds maximum allowed 
Type table entry not valid 

Alias table entry not valid 

size of constants exceeds maximum 

Procedure size exceeds maximum 

Instruction stream not valid 

Size of literals exceeds maximum 


Dictionary entry not valid 


Level of machine interface not supported on target release 


Size of dictionary exceeds maximum 
Internal machine operation not valid 


Size of internal binding table exceeds maximum 


An error was detected in a static storage definition or initalization 


Overlapping initializations not valid 


Dictionary ID is not valid 


Exception Specifications 
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61 

62 
63 

AQ 
BO 
B1 
B2 
B3 
B4 
CO 


Binding specification value not valid 

Copyright component value not valid 

Module limitation exceeded 

Attempt to delete part that may not be deleted 

Object list referential extension not valid 

Symbol resolution list referential extension not valid 

Service program export list referential extension not valid 
Secondary associated spaces list referential extesion not valid 
Program limitation exceeded 


Attempt to delete part that may not be deleted 


Program Execution 


O1 

02 
03 
04 
05 
06 
07 
08 

10 
11 

12 
13 
14 
15 
16 

17 
18 

19 

1A 
1B 
1c 
1D 
1E 
1F 
20 
21 

22 


Return instruction invalid 

Return point invalid 

<D> 

Branch target invalid 

Activation in use by invocation 
Instruction cancellation 

Instruction termination 

Branch target defined by label pointer not valid 
Process object destroyed 

Process object access invalid 
Activation group access violation 
Activation group not found 

Activation group in use 

Invalid operation for program 

Program activation not found 

Default activation group not destroyed 
Invalid source invocation 

Invalid origin invocation 

Invocation offset outside range of current stack 
Invocation not eligible for operation 
Instruction not valid for invocation type 
automatic storage overflow 

activation access violation 

program signature violation 

static storage overflow 

program import invalid 


data reference invalid 
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30 


32 


34 


36 


38 


3A 


23 imported object invalid 

24 = activation group export conflict 

25 import not found 

Resource Control Limit 

01 User profile storage limit exceeded 

02 Security audit journal full or other failure 
Journal 

01 Apply journal changes failure 

02 Entry not journaled 

03 Maximum objects through a journal port limit exceeded 
04 ~=Invalid journal space 

05 Maximum journal spaces attached 

O06 Journal space not at a recoverable boundary 
07 Journal ID not unique 

08 Object already being journaled 

09 Transaction limit list exceeded 

OA Data space index currently journaled 

OB Data space index currently in force mode 
OC Underlying data space not journaled to same journal 
scalar Specification 

01 Scalar type invalid 

02 Scalar attributes invalid 

03 Scalar value invalid 

Source/Sink Management 

01 Source/sink configuration invalid 

02 Source/sink physical address invalid 

03 Source/sink object state invalid 

04 Source/sink resource not available 
Space Management 

01 Space extension/truncation 

02 Invalid space modification 

Template Specification 

01 Template value invalid 

02 Template size invalid 


03 Materialization length exception 


Wait Time-Out 
01 Dequeue 
02 Lock 


Exception Specifications 
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3E 


40 


44 


45 


46 
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03 Wait on event 

04 Space location lock wait 

Service 

01 + Invalid service session state 

02 Unable to start service session 

Commitment Control 

01 Invalid commit block status change 

03 Commit block is attached to process 

04 Commit block controls uncommitted changes 

06 Commitment control resource limit exceeded 

08 Object under commitment control being incorrectly journaled 
10 Operation not valid under commitment control 

11. Process has attached commit block 

12 Objects under commitment control 

13. Commit block not journaled 

14 Errors during decommit 

15 Object ineligible for commitment control 

16 Object ineligible for removal from commitment control 
Dump Space Management 

01 Dump data size limit exceeded,, 

02 = Invalid dump data insertion 

03 Invalid dump space modification 

04 Invalid dump data retrieval 

Domain Violation 

01 Object Domain error 

Heap Space 

01 Heap identifier invalid for the current activacation group 
02 The requested heap space operation is invalid 

03 The heap space has reached it’s maximum allowable size 
04 The requested heap space allocation or reallocation size is invalid 
05 Heap space destroyed 

06 Invalid heap space condition detected 

07 The supplied mark identifier is invalid 

Queue Space 

01 Queue Space not associated with the process 

02 Cannot modify queue space 

03 Invalid message reference key 


04 Queue Space not eligible for destruction 
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Hex 02, Access Group Exceptions 


02 Access Group 


0201 


Object Ineligible for Access Group 


An attempt was made to insert an object into an access group. The operation could not be 
performed for one of the following reasons: 


¢ The object is temporary, or the object is permanent and the access group is temporary. 

¢ The object is restricted by the machine from membership in an access group. 
Information Passed: 

* Access group System pointer 


¢ Object to be inserted System pointer 
(binary O for objects not yet created) 


Instructions Causing Exception: 


e Any create instruction that specifies an access group in the create template 


e Signal Exception 
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Hex 04, Access State Exceptions 


04 Access State | 
0401 Access State Specification Invalid 
An access state not supported by the machine was specified for an object. 
Information Passed 
e The invalid access state Char(1) 
instructions Causing Exception: 
* Set Access State 


¢« Signal Exception 
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Hex 06, Addressing Exceptions 


06 Addressing 


0607 


Space Addressing Violation 


An attempt has been made to operate outside the current extent of a space. 


Information Passed: 


Note: IPS stands for “implicit process space”. 
System object affiliated with the space System pointer 


space offset reference attempted Bin(4) 
This value may be zero when not available. 


Space class Char(1) 


Hex 00 = Primary associated space (includes space objects) 
Hex 01 secondary associated space 

Hex 02 = IPS used for automatic storage 

Hex 03 IPS used for static storage 

Hex 04 = IPS used for heap storage 


Reserved (binary 0) Char(1) 


Secondary associated space number UBin(2) 
This value will be zero when not available, such as when the space is not a secondary asso- 


ciated space. 


Activation group mark ‘UBin(4) 
This value will be zero when not available, such as when the space is not an implicit 
process space. 


Heap space identifier UBin(4) 
This value will be zero when not available, such as when the space is not an implicit 
process space used by a heap space. 


Pointer to start of IPS used for allocation Space pointer 
This value will be zero when not available, such as when the space is not an implicit 
process space. 


Different information is supplied for different space classes. Fields which are not used fora 
given space class will contain zero values. Here is a summary of the information returned (i.e. 
the field values set) for each space class. 


hex 00 (primary associated space, including space objects) 


system pointer to the object 
offset 
space class 


hex 01 (secondary associated space) 


system pointer to the object 
offset 

space class 

secondary space number 


hex 02 (auto) 


system pointer to the Process Control Space 

offset 

Space class 

activation group mark 

space pointer to the start of the IPS from which the allocation was taken 


hex 03 (static) 


system pointer to the Process Control Space 
offset 
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0602 


0603 


0604 


Hex 06, Addressing Exceptions 


* space class 

« activation group mark 

¢ space pointer to the start of the IPS from which the allocation was taken 
hex 04 (heap) 

« system pointer to the Process Control Space 

° offset 

e space class 

e activation group mark 

e heap space identifier . 

* space pointer to the start of the IPS from which the allocation was taken. 


— Note: If the heap space was created to force a new IPS on each allocation this field will 
contain a space pointer to the start of the allocation. 
Instructions Causing Exception: 
e Any instruction using a pointer or scalar as an operand 


e« Any instruction using a scalar as an index, a length suboperand, or a space pointer as a 
base suboperand 


e« Signal Exception 
Boundary Alignment 


A program object has been referenced, and it does not have the proper alignment relative to the 
beginning of a space. Pointers must always be 16-byte aligned. Program objects that are not 
pointers must have at least the alignment specified by the ODT entry.’ 


Information Passed: 
e Addressability to pointer or template Space pointer 
Instructions Causing Exception: 


e Any instruction having a pointer operand or a template operand that requires a specific 
boundary alignment 


Range 


A subscript value in a compound operand array reference is outside the range defined for the 
array. A subscript value of less than 1 or greater than the number of elements defined by the 
array causes this exception. 


A reference to a string has a position and/or length that exceeds the bounds of the string. A 
compound operand that defines a character string that does not completely fall within the 
bounds of the base character string was referenced. A substring with position (P) e1 and length 
(L) e1 does not meet the following constraint (n is the length of the base string): 


P+L-1<n 
Instructions Causing Exception: 
¢ All instructions that use scalar or pointer operands 
e Signal Exception 
External Data Object Not Found 


An unsuccessful attempt was made to resolve a data pointer. The external data object specified 
by the initial value of the data pointer was not found in the process activations. If a program 
name was specified in the symbolic address, then only that program’s activation is considered 
for resolution. If no program was specified, then all of the programs with activations in the 
process are considered for data pointer resolution. 


Information Passed: 
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Hex 06, Addressing Exceptions 


e External data object name Char(32) 
Instructions Causing Exception: 
° Any instruction that references an external data object through a data pointer. 


e Any instruction where a data pointer is used as the scalar value for an index of a length 
suboperand. This includes scalar and pointer operands that may be subscripted. 


¢ Signal Exception 

e Compare Pointer Addressability 

¢ Compare Pointer for Space Addressability 

e Convert Character to Numeric 

« Convert External Form to Numeric 

e Convert Numeric to Character 

« Copy Bytes Left Adjusted 

e Copy Bytes Left Adjusted With Pad 

e Copy Bytes Right Adjusted 

e Copy Bytes Right Adjusted With Pad 

e Copy Numeric Value 

e Edit 

¢ Materialize Pointer 

e Resoive Data Pointer 

e Set Data Pointer Addressability 

e Set Data Pointer Attributes 

e Set Space Pointer From Pointer 

« Set System Pointer From Pointer 
Invalid Space Reference 
An attempt was made to address a space contained in an object that has no space. 
Instruction Causing Exception: 

e Set Space Pointer from Pointer 
Optimized Addressability Invalid 


An instruction attempted to use the internally optimized value of a space pointer that was invalid 
due to the failure of a prior instruction in trying to access the pointer’s value. 


The machine may optimize the retrieval of a pointer’s value by using the value retrieved on one 
instruction for use by multiple instructions that have need to reference the pointer’s value. This 
avoids the overhead of continually retrieving the pointer’s value from storage for every instruc- 
tion that would have need to use it. If, in attempting to retrieve the pointer’s value, an exception 
is detected, the machine marks the internally optimized value as invalid. This is done to provide 
for detecting the invalid addressability upon subsequent execution of instructions that depend on 
the internally optimized value. These instructions have no provision for retrieving the pointer’s 
value from storage. These instructions will not redetect the original exception, but instead 
detect the optimized addressability invalid exception for this condition. This condition can occur 
when an exception is detected during an attempt to retrieve a pointer’s value and the exception 
is ignored which causes execution of the program to continue without successfully retrieving the 
pointer’s value. 
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Hex 06, Addressing Exceptions 


This exception may not be detected on certain cases of internal machine optimizations that may 
be performed on references to space pointer machine objects. A reference to the space data 
addressed by the pointer is necessary to ensure consistent detection of this exception. Although 
the exception may not be detected for initial operations, it will be detected on any subsequent 
operation that references the space data addressed by the space pointer machine objects. 


The optimization of retrieving a pointer’s value can be prevented by specifying the abnormal 
attribute for the pointer. 


This exception may not be detected on the operations listed below under certain cases of 
internal machine optimizations which may be performed on references to space pointer machine 
objects. The operations listed below refer to the value of a space pointer machine object, but do 
not have need to reference the space data the pointer addresses. A reference to the space data 
addressed by the pointer is necessary to insure consistent detection of this exception. Although 
the exception may not be detected for these operations, it will be detected upon any subsequent 
operation which references the space data addressed by the space pointer machine object. 


The following instructions may not detect this exception upon references to a space pointer 
machine object. 


e Add Space Pointer 

¢ Compare Pointer for Space Addressability 
¢ Compare Pointers for Equality 

« Compare Space Addressability 

¢ Set Space Pointer 

¢ Set Space Pointer with Displacement 

¢ Set Space Pointer from Pointer 

¢ Subtract Space Pointer Offset 

¢ Subtract Space Pointers For Offset 


See the particular instruction description for more detail. 
Instructions Causing Exception: 
e Any instruction using a pointer or scalar as an operand 


— Signal Exception 
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08 Argument/Parameter 


0801 


0802 


0803 


Parameter Reference Violation 


An attempt was made to reference an internal or an external parameter for which no corre- 
sponding argument was passed. 


This exception may not be signaled for operations which refer to the value of a space pointer 
machine object, but which do not attempt to reference the space data the pointer addresses. 
The following instructions may not signal this exception upon references to a space pointer 
machine object. 


e Add Space Pointer 

e Compare Pointers for Equality 

e Compare Space Addressability 

e Set Space Pointer 

e Set Space Pointer with Displacement 
e Set Space Pointer from Pointer 

e Subtract Space Pointer Offset 

¢ Subtract Space Pointers For Offset 


See the particular instruction description for more detail. /nstructions Causing Exception: 
e Any instruction that references a parameter operand 
e Signal Exception 
Argument List Length Violation 
An argument list does not properly correspond to the length required by the parameter list. 


Information Passed: 


e Minimum number of arguments allowed Char(2) 
e Maximum number of arguments allowed Char(2) 
e Actual number of arguments allowed Char(2) 


instructions Causing Exception: 
e Call External 
e Transfer Control 
e Signal Exception 
Argument List Length Madification Violation 


An attempt was made to change the length of a variable-length argument list to a value less 
than O or greater than the maximum size of the argument list. 


Instructions Causing Exception: 
e Set Argument List Length 


e Signal Exception 
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0C Computation 
. OCO1 Conversion 
A scalar value cannot be converted to the necessary type in this instruction. 
Instructions Causing Exception: 
¢ Convert Character to Hex 
¢ Convert External Form to Numeric 
¢ Convert SNA to Character 
e Convert MRJE to Character 
e Convert BSC to Character 
e Signal Exception 
0C02 Decimal Data 


The sign or digit codes of a decimal operand, either packed or zoned, contain an invalid value. 
For packed and zoned format, either the sign is outside the valid range of A through F or a digit 
field is outside the range O through J. 


Instructions Causing Exception: 
e Add Numeric 
¢ Compare Numeric Value 
e Convert Character to Numeric 
e Convert Decimal Form to Floating-Point 
& ¢ Convert Numeric to Character 
e Copy Numeric Value 
¢ Divide 
e Divide With Remainder 
¢ Edit 
e Extract Magnitude 
¢ Multiply 
« Negate 
e Remainder 
° Scale 
e Search 
¢ Subtract Numeric 
« Sum 
e Signal Exception 
0C03 Decimal Point Alignment 


The value of a numeric operand cannot be aligned in a 31-digit decimal field. Decimal point 
alignment was attempted by padding with 0’s on the right. Nonzero digits would have to be 
truncated on the left to fit the aligned value into a 31-digit decimal field. 


C Instructions Causing Exception: 
e Add Numeric 
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« Compare Numeric Value 
¢ Subtract Numeric 
e« Signal Exception 

Edit Digit Count 


The number of digit position characters in the mask operand of an Edit instruction is not equal to 
the number of digits in the Source operand value. 


Instructions Causing Exception: 
e Edit 
e« Signal Exception 
Edit Mask Syntax 
The characters of the mask operand do not follow the valid syntax rules for an Edit instruction. 
Instructions Causing Exception: 
e Edit 
e Signal Exception 
Floating-Point Overflow 


The result of a floating-point operation is finite and not an invalid value, but its exponent is too 
large for the target floating-point format. The signed exponent has exceeded 127 in short format 
or 1023 in long format. 


Information Passed: 


e Floating-point value attributes Char(1) 

— Normal bias Bit 0 

— Modified bias Bit 1 

— Rounded to short floating-point Bit 2 

precision 

— NaN Bit 3 

— Reserved (binary 0) Bits 4-7 
e Reserved (binary 0) Char(7) 
¢ Overflowed floating-point value Floating-(8) point 
e Reserved (binary 0) Char(16) 


Instructions Causing Exception: 
e Add Numeric 
« Compute Math Function Using One Input Value 
e Compute Math Function Using Two Input Values 
e Convert Character to Numeric 
e Convert Numeric to Character 
e Convert Decimal Form to Floating-Point 
« Copy Numeric Value 
¢ Divide 
e Extract Magnitude 
« Multiply 
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e Negate 
* Scale 
S ¢ Subtract Numeric 
¢ Signal Exception 
0CO07 Floating-Point Underflow 


The result of a floating-point operation is not zero but has too small an exponent for the destina- 
tion’s format without being denormalized. The signed exponent is less than -126 in short format 
or less than -1022 in long format. 


Information Passed: 


e¢ Floating-point value attributes Char(1) 

— Normal bias Bit 0 

— Modified bias Bit 1 

— Rounded to short floating-point Bit 2 

precision 

— NaN Bit 3 

— Reserved (binary 0) Bits 4-7 
e Reserved (binary 0) Char(7) 
e Underflowed floating-point value . Floating-(8) point 
e Reserved (binary 0) Char(16) 


Instructions Causing Exception: 
= e Add Numeric 

¢ Compute Math Function Using One Input Value 
« Compute Math Function Using Two Input Values 
¢ Convert Character to Numeric 
¢ Convert Numeric to Character 
e Convert Decimal Form to Floating-Point 
¢ Copy Numeric Value 
¢ Divide 
e Extract Magnitude 
¢ Multiply 
« Negate 
e« Scale 
¢ Subtract Numeric 
¢ Signal Exception 

0C08 Length Conformance 


The operand lengths or resultant value length or both do not conform to the rules of the instruc- 
tion: 


.. CVTHC Twice the length of the source operand must be less than or equal to the length of 
the receiver operand. 
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CVTCH The length of the operand must be less than or equal to twice the length of the 
receiver operand. 

CVTMC The length of a record in the receiver was not enough to contain the converted form 
of a record from the source. 

EDIT The length of the resultant edited value must be equal to the length of the receiver 
operand. 

SCAN The length of the compare operand must not be greater than the length of the base 
string. 


SEARCH The length of the find operand plus the value of the location operand must be less 


than or equal to the length of an element of the array operand. 


XLATE The source and receiver operands must be the same length. 


Instructions Causing Exception: 


Convert Character to Hex 
Convert Hex to Character 
Convert MRJE to Character 
Edit 

Extended Character Scan 
scan 

Search 

Signal Exception 


Translate 


0C09 Floating-Point Invalid Operand 


A floating-point invalid operand condition is caused by one of the following conditions: 


A source operand is an unmasked NaN. 

Addition of infinities of different signs and subtraction of infinities of the same sign. 
Multiplication of zero times infinity. 

Division of zero by zero or infinity by infinity. 

Computing the sine, cosine, or tangent function for infinity. 


Computing the arc tangent, exponential, logarithm, square root, or power function for infinity 
when in projective infinity mode. 


Floating-point values compared unordered and no branch or indicator options are specified 
for the unordered, negation of unordered, equal, or negation of equal conditions on compare 
numeric value. 


An unordered resultant condition occurred on a computational instruction because the result 
was NaN, and branch or indicator conditions are specified but unordered, negation of unor- 
dered, zero, or negation of zero conditions are not specified. 


Information Passed: 


Exception type Char(1) 
Hex 00 = Invalid arithmetic operation or operand is unmasked NaN. 

Hex 01 = Invalid branch or indicator conditions. 

Hex 02 through hex FF are reserved. 

Reserved (binary 0) Char(31) 
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Instructions Causing Exception: 
« Add Numeric 
« Compare Numeric Value 
¢ Compute Math Function Using One Input Value 
« Compute Math Function Using Two Input Values 
¢ Convert Character to Numeric 
¢ Convert Floating-Point to Decimal Form 
¢ Convert Numeric to Character 
¢ Copy Numeric Value 
¢ Divide 
¢« Extract Magnitude 
¢ Multiply 
« Negate 
e Scale 
¢« Subtract Numeric 
¢ Signal Exception 
OCOA Size 


An operand was too small to contain a result. This condition is detected only when a fixed-point 
result is too large to be assigned to a fixed-point receiver. The receiver operand is set with the 
result of the operation truncated to the receiver size. 


Instructions Causing Exception: 
e Add Numeric 
¢ Compute Math Function Using One Input Value 
e Compute Math Function Using Two Input Values 
¢« Convert Character to Numeric 
¢ Convert External Form 
¢ Convert Numeric to Character 
e Copy Numeric Value 
¢ Divide 
¢« Divide With Remainder 
¢« Extract Magnitude 
¢ Multiply 
« Negate 
¢ Remainder 
« Scale 
¢ Subtract Numeric 
« Sum 
e¢ Signal Exception 


¢ Trim Length 


Chapter 23. Exception Specifications 23-22 


Hex 0C, Computation Exceptions 


OCOB Zero Divide 
An attempt was made to divide by 0 on a fixed-point divide operation. 3 


Instructions Causing Exception: 


Divide 
Divide With Remainder 


Remainder 


e Signal Exception 


OCOC Invalid Floating-Point Conversion 


This exception is detected on a conversion from binary floating-point to other than a binary 
floating-point format because overflow, infinity, or NaN is detected before conversion is com- 


plete. 


Information Passed: 


Floating-point value attributes Char(1) 

— Normal bias Bit O 

— Modified bias Bit 1 

— Reserved (binary 0) Bit 2 

— NaN Bit 3 

— Infinity ‘Bit 4 

— Reserved (binary 0) Bits 5-7 

Reserved (binary 0) Char(7) ») 
Invalid floating-point value Floating-point (8) 

Reserved (binary 0) Char(16) 


Instructions Causing Exception: 


Add Numeric 

Compute Math Function Using One Input Value 
Compute Math Function Using Two Input Values 
Convert Character to Numeric 

Convert Floating-Point to Decimal Form 
Convert Numeric to Character 

Copy Numeric Value 

Divide 

Multiply 

Negate 

scale 

Subtract Numeric 


Signal Exception 


OCOD Floating-Point inexact Result ; 


This exception is signaled when the rounded result of an operation is not exact because of one 
of the following conditions: 
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¢ The rounded result of an operation is not exact because a value is modified (rounded) to fit 
in a receiver operand and nonzero fraction digits are lost. 


¢ The occurrence of a floating-point overflow condition when that condition is masked and the 
result is no longer exact because it is set to infinity. 


information Passed: 
« Reserved (binary 0) Char(32) 
Instructions Causing Exception: 
e Add Numeric 
¢ Compare Numeric Value 
« Compute Math Function Using One Input Value 
¢ Compute Math Function Using Two Input Values 
e Convert Character to Numeric 
« Convert Decimal Form to Floating-Point 
« Convert Floating-Point to Decimal Form 
e Copy Numeric Value 
¢ Divide 
e Extract Magnitude 
¢ Multiply 
« Negate 
¢ Scale 
e Subtract Numeric 
e Signal Exception 
Floating-Point Zero Divide 


This exception is signaled for a floating-point division operation if the divisor is zero and the 
dividend is a finite nonzero number. 


Instructions Causing Exception: 
¢ Compute Math Function Using Two Input Values 
¢ Divide 
¢ Signal Exception 

Master Key Not Defined 


The cipher operation requested use of the master key but the master key has not been defined 
by the Modify Machine Attributes instruction or is invalid. 


Instructions Causing Exception: 
e Cipher 
¢ Cipher Key 
e Signal Exception 
Weak Key Not Valid 
The key supplied in the template is a weak key and cannot be accepted by the cipher operation. 
Instructions Causing Exception: 


e Cipher 
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« Cipher Key 
¢ Modify Machine Attributes 
¢« Signal Exception 

Key Parity Invalid 


The key supplied in the template does not have odd parity in each byte and is, therefore, unac- 
ceptable for the cipher operation. 


Information Passed: 
e Offset (byte) to the key field Bin(2) 
e Reserved Char(6) 
Instructions Causing Exception: 
e Cipher 
e Modify Machine Attributes 
e Signal Exception 
Invalid Extended Character Data 
The character codes in an extended character data field contain an invalid value. 
Instructions Causing Exception: 
e Copy Extended Characters Left Adjusted With Pad 
¢ Signal Exception | 
Invalid Extended Character Operation 
The operand data types specified for an extended character operation are incompatible. 
Instructions Causing Exception: 
e Copy Extended Characters Left Adjusted With Pad 
e Signal Exception 
Invalid Compressed Data 
The data to be decompressed contains an invalid signature. 
Information Passed: 
e Actual Result Data Length Bin(4) 
Instructions Causing Exception: 
e Decompress Data 
¢ Signal Exception 
Date boundary overflow 


The end result of a date calculation or conversion, for a date exceeds the end of the time line of 
the DDAT 


Instructions Causing Exception: 
Data format error 
The format of the data does not conform to the format that is described in the DDAT. 


Instructions Causing Exception: 
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Data value error 


The data value of a date. time. or timestamp is not valid with respect to the calendar specified in 
the DDAT. 


Instructions Causing Exception: 
Date boundary underflow 


The end result of a date calculation or conversion, the date, precedes the beginning of the time 
line described in the DDAT. 


Instructions Causing Exception: 
Space pointer operands do not point to the same space object 


The program that was running attempted to subtract two space pointers from each other, but the 
pointers did not point to the same space. 


Change the program so that the space pointers point to the same space. 
Information Passed: 
e First space pointer Space pointer 
e Second space pointer Space pointer 
Instructions Causing Exception: 


¢ Signal Exception 
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OE Context Operation 


OE01 


OE02 


Duplicate Object /dentification 


An attempt was made to place addressability in a context to an object having the same name. 
type, and subtype as an existing entry in the context. 


Information Passed: 


« System pointer to the existing object 


¢« Object identification Char(32) 
— Qbject type Char(‘) 
— Object subtype Char(1) 
— Object name Char(30) 


Instructions Causing Exception: 
« All create instructions 
¢ Modify Addressability 
e Rename. Object 
e« Signal Exception 
Object Ineligible For Context 


An attempt was made to delete addressability to an object of a type that may be addressed only 
by the machine context, or an attempt was made to place addressability to an object in a tempo- 
rary or permanent context that may be addressed only by the machine context. 


Information Passed: 


e System pointer to object 


e« Object identification Char(32) 
— Object type Char(1) 
— Object subtype code Char(‘) 
— Object name Char(30) 


Instructions Causing Exception: 
¢ Modify Addressability 


« Signal Exception 
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10 Damage 


1002 


1004 


Machine Context Damage State 


The machine context cannot be referenced because it is in the damaged state. The machine 
context rebuild option of the Reclaim instruction can be used to correct the problem or an |PL 
Can correct the problem. 


Information Passed: 


e Reserved (binary 0) Char(16) 
« VLOG dump ID Char(8) 
e Error class Bin(2) 


e The error class codes for the type of damage detected are as follows: 


Hex 0000 = Previously marked damaged 
Hex 0001 = Detected abnormal condition 
Hex 0002 = Locally invalid device sector 
Hex 0003 = Device failure 


e Auxiliary storage device failure Bin(2) 


This field is defined for error classes hex 0002 and hex 0003. It is the unit number of the 
failing device or O for a main storage failure. 


e Reserved (binary 0) Char(100) 
Instructions Causing Exception: ; 
e Materialize Context 
e Resolve System Pointer 
e Any instruction that resolves a system object that is located by the machine context 
e Signal Exception 
System Object Damage State 
A system object cannot be accessed because it is in the damaged state. 


Information Passed: 


e System pointer to the damaged object System pointer 
« VLOG dump ID Char(8) 
¢« Error class Bin(2) 


e« The error class codes for the type of damage detected are as follows: 


Hex 0000 = Previously marked damaged 
Hex 0001 = Detected abnormal condition 
Hex 0002 = Locally invalid device sector 
Hex 0003 = Device failure 


e Auxiliary storage device indicator Bin(2) 


This field is defined for error classes hex 0002 and hex 0003. It is the unit number of the 
failing device or O for a main storage failure. 


¢« Reserved (binary 0) Char(100) 
Instructions Causing Exception: 
e Any instruction that references a system object 


e« Signal Exception 
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1005 Authority verification terminated due to damaged object 


1044 


Authority verification processing terminated due to a damaged user profile or authorization list 
found during the check of authority for a permanent system object. 


Information Passed 


System Pointer to the object for System pointer 
which authority was being checked 

Reason Code Bin(2) 

0 = Damaged User Profile 

1 = Damaged Authorization List 


(all other values reserved) 
Reserved Char(14) 


System Pointer to the damaged User System pointer 
Profile or Authorization List 


Instructions Causing Exception 


Any instruction with operands or operand lists that refer to a permanent system object 


Signal Exception 


Partial System Object Damage 


Partial damage to a system object has been detected. 


Information Passed: 


system pointer to the damaged object system pointer 
VLOG dump ID Char(8) 
Error Class Bin(2) 


The error class codes for the type of damage detected are as follows: 


Hex 0000 = Previously marked damaged 
Hex 0001 = Detected abnormal condition 
Hex 0002 = Locally invalid device sector 
Hex 0003 = Device failure 


Auxiliary storage device indicator Bin(2) 


This field is defined for error classes hex 0002 and hex 0003. It is the unit number of the 
failing device or O for a main storage failure. 


Reserved (binary QO) Char(100) 


Instructions Causing Exception: 


Any instruction that references a system object 


Signal Exception 


Meaning and recovery: 


For a user profile, partial damage occurs when internal processing is unable to complete 
due to insufficient machine storage. When the system is !PLed, if there is then sufficient 
storage, the interna! processing is completed and the partial damage condition is reset. 
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Conversion Mapping Error 


During conversions of a field from one data representation to another, an error occurred. The 


specific error is indicated in the error type value, below. 
Information Passed: 


The following data is provided: 


e Cursor system pointer 
e Data space number Bin(2) 
e Ordinal entry number Bin(4) 
(0 if signaled during an Insert Data Space 
Entry or an Insert Sequential Data Space 
Entries instruction) 
e Number of fields in error Bin(2) 
¢ Field data (repeated for each field that is in error) 
— Field number Bin(2) 
— Error type Char(2) 
¢ Tolerate all mapping errors exception data 
— Status bits _ Char(2) 
- Bitmap is specified Bit 0 
0 = Bit map is not returned in the exception data 
1 = Bit map is returned in the exception data 
- Join field incurred an error Bit 1 
0 = A join field did not incur an error 
1 = A join field did incur an error 
- No records in group Bit 1 
0 = Group-by processing not in effect or a valid group was returned 
1 = Group-by processing found no records which qualify as part of the 
defined group (set only when grouping WITHOUT a data space index) 
- Reserved (binary zero) Bit 3-15 
— Bit map byte length Bin(2) 
— Bit map identifying the erroneous 
user buffer fields Char(*) 
— Number of first exceptions Bin(2) 
— First exception data Char(14) 
(repeated for each offending field) 
- First error cursor data space Bin(2) 
number 
- First error ordinal entry number Bin(4) 
- First error join cursor ordinal Char(128) 
positions 
- First error field number Bin(2) 
- First error error type Char(2) 


Chapter 23. Exception Specifications 23-30 


Hex 12, Data Base Management Exceptions 


- First error field location Char(1) 


- Reserved Char(5) J 


The ordinal entry number will contain a value of binary Zero when the exception occurs when 
inserting new data space entries or performing group-by and join operations. 


The field number is the relative location of the field as specified when creating the cursor. A 
field number of 1 is the first field in the data field location. 


The error type values are as follows: 


Hex 0001-Conversion: An invalid character was found by the derived operation, Invalid Char- 
acter Scan. 


Hex 0002-Decimal Data: (1) Sign encoding is invalid for packed or zoned format, or (2) digit 
encoding is invalid for packed or zoned format. 


Hex 0006-Floating-Point Overflow: During conversion, a floating-point value exceeded the 
maximum value that can be represented. 


Hex 0007-Floating-Point Underflow: During conversion, a floating-point value became less 
than the minimum value that can be represented. 


Hex 0008-Length Conformance: A length specified for a variable length field was outside the 
limits of that field. 


Hex 0009-Floating-Point Invalid Operand: A floating-point NaN was used as an operand to 
convert from long floating-point format to short floating-point format or from short floating- 
point format to long floating-point format. 


Hex O00A-Size: The destination field is too small to hold all significant digits of the source 
field. 


‘ 
Hex 000C-Invalid Floating-Point Conversion: An invalid floating-point value was used as an J 
operand to convert floating-point to packed decimal or floating-point to binary. 


Hex O00D-Floating-Point Inexact Result: In a conversion operation, a floating-point value had 
at least one bit of precision rounded away. 


Hex 0012- Invalid extended character data; The character data in an extended character data 
field contain an invalid value. 


Hex 0015-Date boundary overflow: The end result of a date calculation or conversion, a 
date, exceeds the end of the time line described in the DDAT. Reference the Common Tem- 
plate Appendix for information on the DDAT. 


Hex 0016-Data format: The format of the data does not conform to the format that is 
described in the DDAT. Reference the Common Template Appendix for information on the 
DDAT. 


Hex 0017-Data value: The data value of a date, time, or timestamp is invalid with respect to 
the calendar specified in the DDAT. Reference the Common Template Appendix for informa- 
tion on the DDAT. 


Hex 0018-Date boundary underflow: The end result of a date calculation or conversion, a 
date, precedes the beginning of the time line described in the DDAT. Reference the 
Common Template Appendix for information on the DDAT. 


Hex 0019-Null status: An invalid situation exists relating to null capable fields. On retrieve 

related instructions, a null field was encountered and a nuil map was not provided with the 
instruction. On insert/update instructions, a null map was provided and indicated a field | 
which is not null capable should be set to null or the null map contains an invalid null or not Ja 
null value. 


Chapter 23. Exception Specifications 23-31 


Hex 12, Data Base Management Exceptions 


These errors are equivalent to the computational exceptions numbered 0C01, 0CO2, OCO6, 0C07, 
O0C08. OCO9. OCOA, OCOC. OCOD, 0C12, 0C14. 0C15, OC 16, and 0C17. and occur for similar reasons. 


The bit map is specified bit indicates if the bit map identifying the erroneous user buffer fields is 
present in the exception data 


The join field incurred an error bit indicates if any join fields incurred mapping errors. This bit is 
always binary zero for non-join cursors. 


The bit map identifying the erroneous user buffer fields maps each field of the user buffer to a 
bit map in a one-to-one correspondence. Field 1 is bit 1, field 2 is bit 2, etc. If the bit corre- 
sponding to a user buffer field is 1 then that field is erroneous and has been replaced with the 
default value (blank for character, zero for numeric). The length of the bit map is given by: 


(((# of fields in user buffer) + 7)/8 +1)&’FFFE’X. 


The first exception data area identifies the first field that incurred an error when a cursor 
created with the tolerate all mapping errors attribute is being used for retrieval operations. The 
field identified is not necessarily represented in the returned record nor is it necessarily repres- 
ented in the bitmap of erroneous fields since it may not have been mapped to the user buffer. 
Instead, this is the very first field which incurred an error in the series of mappings which ulti- 
mately produced the record-view in the user’s buffer. 


The first error cursor data space number will contain binary zero when the error occurs during 
group-by derived field operations. 


The first error ordinal entry number will contain binary zero when the error occurs during 
group-by derived field operations or while processing default values during a join operations. 


The first error join cursor ordinal positions area is meaningful only on operations involving a join 
cursor and is zero in instances of non-join. It will also be zero if the exception occurs during 
group-by processing or derived field operations. Each ordinal is 4 bytes in length. All current 
ordinals associated with a join cursor are returned. 


The first error field number is as described for field number above. 


The first error error-type is as described for error type above with the addition of the following 
types: 
Hex 000B -An attempt was made to divide by zero in a fixed point divide operation. 


Hex OOOE -An attempt has been made to divide by zero in a floating point divide operation. 


The first error field location identifies the buffer where the first error occurred. The following 
values can be returned: 


00 = Data space entry 
01 
02 


Instructions Causing Exception: 


Cursor intermediate buffer 


Group-by intermediate buffer 


e Copy Data Space Entries 

e Insert Data Space Entry 

e Insert Sequential Data Space Entries 

e Retrieve Data Space Entry 

e Retrieve Sequential Data Space Entries 
e Update Data Space Entry 


e Signal Exception 
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1202 Key Mapping Error 


During conversions of a field from one data representation to another, an error occurred. The ) 
Specific error is indicated in the error type value, below. 


Information Passed: 


The following data is provided: 


Cursor 
Data space number 
Ordinal Entry Number 
Number of fields in error 
Field data (repeated for each field that is in error) 
e Field number 
e Error type 
Tolerate all mapping errors exception data 
e Status bits 
— Bitmap is specified 


0 = Bit map is not returned in the exception data 
1 = Bit map is returned in the exception data 


— Reserved (binary zero) 
— Reserved (binary zero) 
e Bit map byte length 


e Bit map identifying the erroneous 
key buffer fields 


e Number of first exceptions 


e First exception data 
(repeated for each offending field) 


— First error cursor data space 
number 


— First error ordinal entry number 
— Reserved 

— First error field number 

— First error error type 

— First error field location 


— Reserved 


System pointer 
Bin(2) 

Char(4) 

Bin(2) 


Bin(2) 
Char(2) 


Char(2) 
Bit O 


‘Bit 1 


Bit 2-15 
Bin(2) J 


Char(*) 
Bin(2) 
Char(144) 


Bin(2) 


Bin(4) 
Char(128) 
Bin(2) 
Char(2) 
Char(1) 
Char(5) 


The field number is the relative location of the field as specified when creating the cursor. A 
field number of 1 is the first field in the data field location. 


The error type values are as follows: 


Hex 0002-Decimal Data: (1) Sign encoding is invalid for packed or zoned format, or (2) digit 


encoding is invalid for packed or zoned format. 


Hex 0006-Floating-Point Overflow: During conversion, a floating-point value exceeded the 


maximum value that can be represented. 
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¢ Hex 0007-Floating-Point Underflow: During conversion, a floating-point value became less 
than the minimum value that can be represented. 


e Hex 0008-Length Conformance: A length specified for a variable length field was outside the 
limits of that field. 


¢ Hex Q009-Floating-Point [Invalid OQperand: A floating-point NaN was used as an operand to 
convert from long floating-point format to short floating-point format or from short floating- 
point format to long floating-point format. 


e Hex OOOA-Size: The destination field is too small to hold all significant digits of the source 
field. 


« Hex 000C-Invalid Floating-Point Conversion: An invalid floating-point value was used as an 
operand to convert floating-point to packed decimal or floating-point to binary. 


e Hex 000D-Floating-Point Inexact Result: In a conversion operation, a floating-point value had 
at least one bit of precision rounded away. 


e Hex 0014-Date boundary underflow: The end result of a date calculation or conversion, a 
date, precedes the beginning of the time line described in the DDAT. Reference the 
Common Template Appendix for information on the DDAT. 


e Hex 0015-Date boundary overflow: The end result of a date calculation or conversion, a 
date, exceeds the end of the time line described in the DDAT. Reference the Common Tem- 
plate Appendix for information on the DDAT. 


e Hex 0016-Data format: The format of the data does not conform to the format that is 
described in the DDAT. Reference the Common Template Appendix for information on the 
DDAT. 


e Hex 0017-Data value: The data value of a date, time, or timestamp is invalid with respect to 
the calendar specified in the DDAT. Reference the Common Template Appendix for informa- 
tion on the DDAT. 


e Hex 0018-Null status: An invalid situation exists relating to null capable fields. On 
instructions that materialize a key, a nuil field was encountered and a null map was not pro- 
vided with the instruction. On instructions with a key as input, a null map was provided and 
indicated a field which is not null capable should be set to null or the null map contains an 
invalid null or not null value. 


e Hex OOFO-A substring set cursor operation was requested. The byte count specified ended in 
a key field that cannot be severed. This key field type could be but is not limited to: binary, 
floating point, date, or timestamp. 


These errors are equivalent to the computational exceptions numbered OCO2, 0C06, 0C07, 0C08, 
OCOS, OCOA, OCOC, OCOD, 0014, 0015, 0C16, and 0C17, and occur for similar reasons. 


The ordinal entry number field will be zero if the exception occurred on input key mapping. For 
output key mapping, ordinal entry number will contain the ordinal number of the DSE which 
caused the exception. 


The bit map is specified bit indicates if the bit map identifying the erroneous user buffer fields is 
present in the exception data 


The bit map identifying the erroneous key buffer fields maps each field of the key buffer to a bit 
map in a one-to-one correspondence. Field 1 is bit 1, field 2 is bit 2, etc. If the bit corresponding 
to a key buffer field is 0 then that field incurred no errors. If the bit corresponding to a key 
buffer field is 1 then that field is erroneous and has been replaced with the default value (blank 
for character, zero for numeric). The length of the bit map is given by: 


(((# of fields in user buffer) + 7)/8 + 1)&’FFFE’X. 


The first exception data area identifies the first field that incurred an error when a cursor 
created with the tolerate all mapping errors attribute is being used for retrieval operations. The 
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field identified is not necessarily represented in the returned key nor is it necessarily repres- 

ented in the bitmap of erroneous fields since it may not have been mapped to the key buffer. 

Instead, this is the very first field which incurred an error in the series of mappings which ulti- 
mately produced the Key-view in the key buffer. 


The first error cursor data space number will contain binary zero when the error occurs during 
group-by derived field operations. 


The first error ordinal entry number will contain binary zero when the error occurs during 
group-by derived field operations. 


The first error field number is as described for field number above. 


The first error error-type is as described for error type above with the addition of the following 
types: 


000B An attempt was made to divide by zero in a fixed point divide operation. 
OOOE An attempt has been made to divide by zero in a floating point divide operation. 


The first error field location identifies the buffer where the first error occurred. The following 
values can be returned: 


00 = Data space entry 
03 Intermediate key buffer 


Instructions Causing Exception: 
e Copy Data Space Entries (mapping from template) 
e Materialize Cursor Attributes (mapping key out to buffer) 
e Retrieve Sequential Data Space Entries (mapping key to buffer) 
e Set Cursor (mapping key in/out) 
e Signal Exception 
Cursor Not Set 


An attempt was made to perform a data base operation using a cursor that is not set to address 
a data space entry. 


Information Passed: 
e System pointer to cursor 
e Data space number Bin(2) 
The data space number will be Zero for a non-join cursor. 
Instructions Causing Exception: 
e Retrieve Data Space Entry 
e Set Cursor 
¢ Signal Exception 
Data Space Entry Limit Exceeded 


The operation caused the user-provided maximum number of entries limitation for the data © 
space to be exceeded. 


Information Passed: 


e Cursor (binary 0 for instruction System pointer 
not involving a cursor) 
e Data space System pointer 


Instructions Causing Exception: 
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Data Base Maintenance (insert default entries and insert deleted entries option) 


Insert Data Space Entry 
Insert Sequential Data Space Entries 


Signal Exception 


1205 Data Space Entry Already Locked 


An attempt has been made to lock a data space entry using the Set Cursor instruction when the 
data space entry is already locked to a cursor (this cursor or another cursor) or to a commit 
block that is not attached to this process. A system pointer to the process control space of the 
process that activated the cursor or attached the commit block that holds the lock is returned. 


1206 


1207 


Information Passed: 


Cursor 

Data space 

Ordinal entry number 
Return code (bit significant) 


Hex 00 = Locked to another process 
Hex 01 Locked to current process 


li 


Reserved (binary 0) 


Process control space 


Instructions Causing Exception: 


e Set Cursor 


e Signal Exception 


Data Space Entry Not Found 


System pointer 
Bin(2) 

Bin(4) 

Char(1) 


; Char(9) 


System pointer 


An attempt has been made to refer to a data space entry that could not be found because the 
entry has been deleted or its key has been omitted from the data space index. 


Information Passed: 


e Cursor 


e Data space number 


Instructions Causing Exception: 


e Retrieve Data Space Entry 


e Set Cursor 


e Signal Exception 


Data Space Index Invalid 


System pointer 
Bin(2) 


The index specified for a data base operation is not usable. 


Information Passed: 


e Cursor 


(binary O for instructions not involving cursor) 


¢ Data space index 


Instructions Causing Exception: 


¢ Activate Cursor 


System pointer 


system pointer 
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« Copy Data Space Entries 
« Retrieve Data Space Entry 
« Retrieve Sequential Data Space Entries 
* Set Cursor 
* Signal Exception 
Incomplete Key Description 


The cursor cannot be set by key for this data space index because the output mapping template 
used to create this cursor failed to provide a description of each field that comprises the key, or 
an alternate entry definition supplied at Create Cursor differs from the entry definition used at 
Create Data Space Index. 


Information Passed: 
e Cursor System pointer 
e Data space number of the key format selected Bin(2) 
Instructions Causing Exception: 
e Copy Data Space Entries 
e Create Cursor 
e Set Cursor 
e Signal Exception 
Duplicate Key Value in Existing Data Space Entry 


An attempt has been made to insert or update a data space entry in a data space over which a 
unique keyed index has been built, and the data space entry has a key value identical to an 
existing data space entry addressed by the index. 


Information Passed: 


e Cursor (binary 0 for system pointer 
operations not involving a cursor) 


e Data space index System pointer 


e The data space number of the Bin(2) 
entry associated with the key already in the data space index 


e The ordinal number of the Bin(4) 
entry associated with the key already in the data space index 


e The data space number of the Bin(2) 
entry that was being added or changed and caused the exception 


¢ The ordinal number of the entry Bin(4) 
that was being changed and caused the exception(0 if an insert was being attempted) 


Instructions Causing Exception: 
e Apply Journaled Changes 
¢ Copy Data Space Entries 
e Insert Data Space Entry 
e Insert Sequential Data Space Entries 
e Update Data Space Entry 


¢ Signal Exception 
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End of Path 
The end of an access path was reached when an attempt was made to position a cursor. 
Information Passed: 

« Cursor System pointer 
Instructions Causing Exception: 

¢« Retrieve Sequential Data Space Entries 

e Set Cursor 

e Signal Exception 
Duplicate Key Value Detected 


While creating or rebuilding a data space index with the unique key attribute, entries were found 
to generate the same key value. The build detected up to a maximum of 20 duplicate key values 
before terminating. 


Information Passed: 


e Data space index System pointer 
¢ Number of duplicates detected Bin(2) 
e (Repeated for each duplicate) 

— Data space number of first entry Bin(2) 

— Ordinal number of first entry - Bin(4) 

— Data space number of second Bin(2) 

entry 
— Ordinal number of second entry Bin(4) 


Instructions Causing Exception: 

e Create Data Space Index 

e Data Base Maintenance (rebuild option) 

e Signal Exception 
No Entries Locked 
No data space entries were locked to this cursor. 
Information Passed: 

e« Cursor System pointer 
Instructions Causing Exception: 

« Delete Data Space Entry 

e Update Data Space Entry 

e Signal Exception 
Duplicate Key Value in Uncommitted Data Space Entry 


An attempt has been made to insert or update a data space entry in a data space over which a 
unique keyed index has been created, and the data space entry has a key value identical to a 
data space entry key value that has been deleted or changed under commitment control but is 
still reserved by the index. The insert or update cannot be done until the uncommitted changes 
are committed. 


Information Passed: 


* Cursor (binary 0 for System pointer 
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operations not involving a cursor) 
e Data space index system pointer 


e The data space number of the entry Bin(2) 
associated with the key reserved in the data space index 


¢ The ordinal number of the entry Bin(4) 
associated with the key reserved in the data space index 


¢« The data space number of the entry Bin(2) 
that was being added or changed and caused the exception 


¢« The ordinal number of the entry that Bin(4) 
was being changed and caused the exception (zero if an insert was being attempted) 


Instructions Causing Exception: 
« Copy Data Space Entries 
¢« Insert Data Space Entry 
e Insert Sequential Data Space Entries 
e Update Data Space Entry 


¢ Signal Exception 


1213 Invalid Mapping Template 


An error was detected in a mapping template. The data space number indicates the template in 
the mapping template list that contains the error. This field will equal 1 for a group-by mapping 
template, and will reference the appropriate template for the per data space mapping templates 
for Create Cursor and Create Data Space Index instructions. This field will contain a zero when 
an intermediate mapping table is missing. 


The template field number indicates which field number is in error for the scalar part of the 
mapping template (number of bytes in mapping template and mapping type). The contents of 
the reserved field immediately following the mapping type field is ignored (only present when 
intermediate mapping is specified). 


The template field number also indicates the field in error for input and output mapping tables. 
Field number equal O indicates the template field number of bytes in the mapping template, field 
number equal 1 indicates field designating input mapping type, field number equal 2 indicates 
field designating output mapping type, field number equal 3 indicates field designating number 
of fields in the input/output mapping tables, and so forth. Each specification in the input/output 
tables is considered one field for counting purposes. 


When an intermediate mapping table is in error, the template field number will equal 0. The 
offset to field in error field will designate the offset to the field from the start of the intermediate 
mapping table. Offset equal 0 designates the field number of intermediate mapping specifica- 
tions, and so forth. 


Possible errors are an invalid value, a value that exceeds allowed range, a length that is invalid 
for the specified type or a type that is inconsistent with the type specified for the field in the data 
space, key description, or an intermediate buffer description. 


The invalid mapping template exception will not be signaled when a data pointer fails verifica- 
tion. The normal exception associated with verifying data pointers will be signaled instead. 


Information Passed: 
¢ Data space number Bin(2) 


¢ Template field number Bin(2) 
(valid only for input/output mapping tables and the scalar part of the mapping template; 
number of bytes in template, input mapping type, output mapping type) 
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Char(1) 


Hex 00 = Per data space mapping template (input/output mapping table and scalar part of 


template) 
Hex 01 = Per data space mapping template (output intermediate mapping table) 
Hex 02 = Group-by intermediate mapping table 
Hex 03 = Derived key intermediate mapping table 
Reserved Char(1) 
Offset to field in error Bin(4) 
(valid only for intermediate mapping table errors) 
Error type Char(2) 


(valid only for intermediate mapping table errors) 
GENERAL ERROR CODES 


Hex 0000 
Hex 0001 
Hex 0300 
Hex 1000 
Hex 1012 
Hex 1014 


Data Pointer error 

Reserved field invalid 

Missing Intermediate mapping table 

Operation field error 

Specified Operation invalid for Variable length fields 
Invalid Null Operation modifier 


OPERAND 1 ERROR CODES 


Hex 8010 
Hex 8020 
Hex 8040 
Hex 8080 
Hex 8008 
Hex 8004 
Hex 8001 
Hex 8400 
Hex 8088 
Hex 8082 


Hex 8048 = 


Hex 8044 


Operand 1 Location invalid 

Operand 1 Length invalid 

Operand 1 Field type invalid 

Operand 1 Field number invalid 

Operand 1 Start character invalid 

Operand 1 End character invalid 

Operand 1 Reserved Area invalid 

Operand 1’s Array Position of the Data Pointer is invalid 

Operand 1’s DDAT is invalid 

Operand 1’s Preferred format or separator is invalid 

Operand 1’s Start or End character referenced an invalid field type for a 
Substring operation 

Operand 1 is a Split Variable length field that is not compatible with the 
specified operation 


OPERAND 2 ERROR CODES 


Hex 4010 
Hex 4020 
Hex 4040 
Hex 4080 
Hex 4008 
Hex 4004 
Hex 4001 
Hex 4100 
Hex 4400 
Hex 4088 
Hex 4044 


Hex 4022 


Operand 2 Location invalid 

Operand 2 Length invalid 

Operand 2 Field type invalid 

Operand 2 Field number invalid 

Operand 2 Start character invalid 

Operand 2 End character invalid 

Operand 2 Reserved Area invalid 

Operand 2’s Array Position of the Translate Table is invalid 
Operand 2’s Array Position of the Data Pointer is invalid 
Operand 2’s DDAT is invalid 

Operand 2 is a Split Variable length field that is not compatible with the 
specified operation 

Operand 2’s Immediate Value or Length is invalid 


RESULT ERROR CODES 


Hex 2020 
Hex 2040 


Result Length invalid 
Result Type invalid 


23-40 
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Hex 2001 = Result Reserved area invalid 
Hex 2002 = Result Rounding mode invalid 
Hex 2004 = Result Type modifier is invalid 
Hex 2088 = Result’s DDAT Is invalid 


—- DATA POINTER ERRORS 


Hex 0020 = Data Pointer length is invalid 
Hex 0040 = Data Pointer field type is invalid 


e Error Types for Input and Output mapping templates 


Hex 0001 = _ Field Location is invalid 

Hex 0002 = Field Type is invalid 

Hex 0003 = Field Length is invalid 

Hex 0004 = Reserved area is not zero 

Hex 0005 = DDAT number references an invalid DDAT number 

Hex 0006 = DDAT number references an invalid format code 

Hex 0007 = DDAT number references an invalid preferred format or separator 

Hex 0008 = Type modifier is invalid 

Hex 0009 = Variable Length/Type mismatch 

Hex OOOA = DDAT offset mismatch between mapping template DDAT number and field 
table DDAT offset 

Hex 00OO0OB = Mapping Conversion is invalid 

Hex OOOC = Mapping a pseudo Date/Time field that is variable length and the fixed allo- 


cation length is greater than zero and less than the maximum size of the field. 
Instructions Causing Exception: 
e Create Cursor 
e Signal Exception 
Invalid Selection Template 


An error was detected in a selection template. The data space number indicates which template 
in the selection template list contains the error. This field will equal 1 for a group-by selection 
template, and will reference the appropriate template for the per data space mapping template 
for Create Cursor and Create Data Space Index. 


The offset to field in error indicates which field is in error in the selection template. The offset 
equal 0 designates the field length of selection template is in error, offset equal 4 designates the 
field number of selection descriptors is in error, and so forth. 


The invalid selection template exception will not be signaled when a data pointer fails verifica- 
tion. The normal exception associated with verifying data pointers will be signaled instead. 


Information Passed: 


e Data space number (position list Bin(2) 
¢ Offset to field in error Bin(4) 
¢ Selection template type Char(1) 


Hex 00 = Per data space selection 
Hex 01 = Group-by selection 


e Reserved Char(1) 
e Selection descriptor errors Char(2) 
— Descriptor type error Bit O 
— Operand/operation error Bit 1 
— Maximum number specifications Bit 2 
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exceeded 
— Literal content in error Bit 3 
— Reserved Bits 4-7 
— Operand location invalid Bit 8 
— Field number invalid Bit 9 
— Starting offset invalid Bit 10 
— Ending offset invalid Bit 11 
— Array position of data pointer Bit 12 
invalid 
— Offset to pattern descriptor invalid Bit 13 
— Number pattern descriptor invalid Bit 14 
— Reserved field invalid Bit 15 
e Pattern descriptor error types Char(2) 
— Descriptor type invalid Bit 0 
— Descriptor field invalid Bit 1 
— Reserved Bits 2-7 
— Field location invalid Bit 8 
— Field number invalid Bit 9 
— Starting offset invalid Bit 10 
— Ending offset invalid Bit 11 
— Array position of data pointer Bit 12 
invalid 
— Span type invalid Bit 13 
— Span width invalid Bit 14 
— Reserved field invalid Bit 15 


Instructions Causing Exception: 
¢« Create Cursor 
e Signal Exception 
Data Space Not Addressed by Index 


An entry in the data space list does not address the same data space that is addressed by the 
corresponding entry in the data space list defined for the data space index. 


Information Passed: 


e Entry in the data space list of Space pointer 
the Create Cursor instruction template 


Instructions Causing Exception: 
e Create Cursor 
e Signal Exception 
Data Space Not Addressed by Cursor 


An entry in the data space list does not address the same data space that is addressed by the 
corresponding list that is defined for the cursor. 
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Information Passed: 


e Cursor system pointer 


e Entry in the data space list Space pointer 
of the Activate Cursor instruction template 


Instructions Causing Exception: 
¢ Activate Cursor 
e Signal Exception 
Key Value Changed Since Set Cursor 


The data space index key for the entry currently addressed by the cursor has changed since the 
cursor was set. The former value of the key was instrumental in finding the entry and is no 
longer valid; therefore, the entry is no longer the expected entry. 


Information Passed: 
e Cursor system pointer 
e Data space number Bin(2) 
Instructions Causing Exception: 
e Retrieve Data Space Entry 
« Set Cursor 
e Signal Exception 
Invalid Key Value Modification 


An attempt to update a data space entry would result in a difference key value when the Update 
Data Space Entry instruction specified the inhibit key change option. This exception is signaled 
for rejected key values if the rejected key image would change on the update, regardless of 
whether the updated key image would be rejected or selected. 


Note: Updating a deleted data space entry is not a change in the key image. 


Information Passed: 


e Cursor System pointer 
« Data space number Bin(2) 
e Ordinal number of entry Bin(2) 


Instructions Causing Exception: 
e Update Data Space Entry 
¢ Signal Exception 

Invalid Rule Option 


The cursor has addressability to a data space index and the current cursor setting allows only 
rule options of relative or ordinal. 


Information Passed: 

e Cursor System pointer 
Instructions Causing Exception: 

e Retrieve Sequential Data Space Entries 

e Set Cursor 


¢« Signal Exception 
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Data Space Entry Size Exceeded 


The sum of the field lengths in the entry definition template exceeds 32 766 bytes which is the 
maximum size allowed for a data space entry. 


Instructions Causing Exception: 
« Create Data Space 
e Signal Exception 
Logical Data Space Entry Size Limit Exceeded 


The user’s view of the data space entry (defined by the mapping code) exceeds 32 766 bytes, 
which is the maximum size allowed. 


Information Passed: 


e Template number (position list) Bin(2) 
e Template type Char(1) 
Hex 00 = Input mapping template 
Hex 01 = Output mapping template 
Hex 02 = Intermediate mapping template 
Hex 03 = Group-by output mapping template 
Hex 04 = Group-by intermediate mapping template 


Instructions Causing Exception: 
e Create Cursor 
e Signal Exception 

Key Size Limit Exceeded 


The sum of the key field lengths plus the specified fork characters exceeds 120 bytes, which is 
the maximum size allowed for a data space index key. 


Information Passed: 

e Data space number Bin(2) 
Instructions Causing Exception: 

e Create Data Space Index 

e Signal Exception 
Logical Key Size Limit Exceeded 


The user’s view of the data space index key exceeds 32 766 bytes, which is the maximum size 
allowed. 


Information Passed: 

e Data space number Bin(2) 
Instructions Causing Exception: 

e Create Cursor 

e Signal Exception 
Unable to Maintain a Unique Key Data Space Index 


An attempt has been made to insert or update a data space entry in a data space over which a 
unique keyed index exists that has been implicitly invalidated. 


Information Passed: 


e Cursor (binary 0 for System pointer 
Operations not involving a cursor) 
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« Data space 

e Data space index (invalidated) 
Instructions Causing Exception: 

¢ Apply Journaled Changes 

e Copy Data Space Entries 

e Insert Data Space Entry 

¢« Insert Sequential Data Space Entries 

e Update Data Space Entry 

e¢ Signal Exception 


1225 Invalid Data Base Operation 


system pointer 


system pointer » 


A data base operation was attempted through a cursor whose activation options indicated that 


the operation was not to be allowed. 
Information Passed: 
e Cursor 


e Extended activation functions 
(as defined in the cursor activation template) 


e Operation attempted 


Hex 80 = Retrieval of data space entry 
Hex 40 = Update of data space entry 
Hex 20 = Delete of data space entry 
Hex 10 = Insert of data space entry 


Instructions Causing Exception: 
¢ Copy Data Space Entries 
e Delete Data Space Entry 
e Insert Data Space Entry 
e Insert Sequential Data Space Entries 
e Retrieve Data Space Entry 
e Retrieve Sequential Data Space Entries 
e Update Data Space Entry 


e Signal Exception 


1226 Data Space Index with Invalid Floating-Point Field Build Termination 


System pointer 
Char(2) 


Char(1) 


While creating or rebuilding a data space index that contains floating-point keys, an invalid 
floating-point value was encountered. Up to 20 instances of these types of errors may be found 


before the instruction is terminated. 
Information Passed: 


e Data space index 
(binary O is signaled during creation) 


e Number of errors detected 
e Error description (repeated for each selection routine error) 
— Data space number 


— Ordinal entry number 


System pointer 


Bin(2) 


Bin(2) 
Bin(4) 
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— Reason code Char(1) 
Hex 01 = Floating-point NaN detected 
— Reserved (binary 0) Char(1) 


Instructions Causing Exception: 


Create Data Space Index 
Data Base Maintenance 


Signal Exception 


Data Space Index Key with Invalid Floating-Point Field 


An attempt was made to insert or update a data space entry in a data space under a data space 
index that contains floating-point key fields, or a key is being used to search a data space index 
that contains floating-point key fields and a floating-point key field contains an invalid value. 


Information Passed: 


Cursor (binary 0 for system pointer 
Operations not involving a cursor) 

Data space System pointer 
Data space index System pointer 
Data space number (in the data Bin(2) 

space list of the data space index) | 

Ordinal entry number (zero Bin(4) 

if entry was being inserted) 

Reason code Char(1) 


Hex 01 = Floating-point NaN detected 
Reserved Char(1) 


Cursor data space number Bin(2) 


Instructions Causing Exception: 


Apply Journaled Changes 

Data Base Maintenance 

Copy Data Space Entries 

Insert Data Space Entry 

Insert Sequential Data Space Entries 
Set Cursor | 
Update Data Space Entry 


Signal Exception 


Specified Data Space Entry Rejected 


An attempt has been made to position a cursor to a specific data entry but the retrieval selection 
criteria has rejected the entry. 


Information Passed: 


Cursor System pointer 
Data space number Bin(2) 
Ordinal number Bin(4) 
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Instructions Causing Exception: 
e Retrieve Data Space Entry > 
*« Set Cursor 2 
¢« Signal Exception 
1232 Join Value Changed 


A join value in a data space entry field used in the current join position in the cursor has 
changed since the cursor was positioned. The former value of the field was instrumental in per- 
forming the join operation and is no longer valid; therefore, the entry is no longer the expected 


entry. 

Information Passed: 
e Cursor System pointer 
e Data space number in cursor Bin(2) 


associated with changed field 
Instructions Causing Exception: 
e Retrieve Data Space Entry 
e Set Cursor 
e Signal Exception 
1233 Data Space Index with Non-User Exit Selection Routine Build Termination 


While creating or rebuilding a data space index that contains a non-user exit selection routine, 
data space entries were encountered which resulted in an error in the selection routine. The 
build, before terminating, found up to 20 instances of these types of errors. The instruction is 


terminated. wi 


Information Passed: 


e Data space index System pointer 
(binary zeros if signaled during creation) 

e Number of errors detected Bin(2) 

e Reserved Char(4) 

e Error description Char(22) 
(repeated for each selection routine error) 
— Data space number Bin(2) 
— Ordinal entry number Bin(4) 
— Reserved (binary Q) Char(6) 
— Error type Char(2) 
— Operand 1 field data Char(4) 
— Field number Bin(2) 
— Field location Char(1) 


Hex 00 = Data space entry 

Hex 01 = Cursor intermediate buffer 
Hex 03 = Intermediate key buffer 
Hex 04 = Key field 


— Reserve Char(1) a 
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¢ Operand 2 field data Char(4) 
(Same as operand 1 field data) 


The field number designates the relative location of the field as specified when creating the 
cursor. index, or data space. Field number equal 1 is the first field in the field location. 


The error type values are as follows: 


Hex 0000-A tolerated exception occurred during derived field mapping and was detected during 
non-user exit selection when the field incurring the error was referenced. 


Hex 0002-decimal data: (1) Sign encoded is invalid for packed or zoned format, (2) Digit 
encoding is invalid for packed or zoned format. 


Hex 0009-floating-point invalid operand: A floating-point NaN was used as an operand in a com- 
parison. 


Hex 0012-Invalid Extended Character Data; A character code in an extended character data field 
contains an invalid value. 


Instructions Causing Exception: 
e Activate Cursor (over delayed maintenance data space index) 
e Create Data Space Index 
e Data Base Maintenance (rebuild data space index) 
¢ Modify Data Space Index Attributes 
e Signal Exception 
1234 Non-User Exit Selection Routine Failure 


An attempt has been made to insert, retrieve, or update a data space entry in a data space, and 
an error was encountered in a non-user exit selection routine. 


Information Passed: 


e Cursor (binary 0 for System pointer 
operations not involving a cursor) 
e Data space System pointer 
e Data space index (binary 0 System pointer 
if selection error not involving the index) 
e Join cursor ordinal positions Char(128) 
e Error description Char(22) 
— Index data space number Bin(2) 
(binary 0 if selection error not on the index) 
— Cursor data space number Bin(2) 
(binary O for operations not involving a cursor) 
— Ordinal entry number (0, if entry Bin(4) 
was being inserted or group-by selection) 
— Reserved Char(4) 
— Error type Char(2) 
— Operand 1 field data (0 if literal) Char(4) 
Field number Bin(2) 
Field location Char(‘1) 


Hex 00 = Data space entry 
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Hex 01 = Cursor intermediate buffer 
Hex 02 = Group-by intermediate buffer 


. Hex 03 = Intermediate key buffer ») 
Hex 04 = Key field 
Reserved Char(1) 
— OQOperand 2 field data Char(4) 
(Same as operand 1 field data) 
— Operand 3 field data Char(4) 


(Same as operand 1 field data) 


The field number designates the relative location of the field as specified when creating the 
cursor, index, or data space. Field number equal 1 is the first field in the field location. A field 
number equal 0 designates there is no exception data for this operand. 


The error type values are identical with those received for exception hex 1233. 


The ordinal entry number will contain a binary zero value if the exception occurs while proc- 
essing default values during a join operation. 


The join cursor ordinal positions area is meaningful only on operations with a join cursor and is 
zero otherwise. It will be zero for group-by selection. Each ordinal number occupies 4 bytes. 
All current ordinal numbers associated with a join cursor are returned. 


Instructions Causing Exceptions 
e Apply Journaled Changes 
e Data Base Maintenance (insert default entries) 
e Insert Data Space Entry 
e Insert Sequential Data Space Entries J 
e Retrieve Data Space Entry 
e Retrieve Sequential Data Space Entry 
e Set Cursor 
e Update Data Space Entry 
¢« Signal Exception 

No Mapping Code Specified 


Cursor cannot be used to perform inserts, retrieves, or updates with the specified data space 
due to no data space entry input mapping code or no output mapping code specified in a Create 
Cursor instruction. 


Information Passed: 
e Cursor System pointer 
e Data space number Bin(2) 
Instructions Causing Exception: 
e Insert Data Space Entry 
e Insert Sequential Data Space Entries 
e Retrieve Data Space Entry 
e Retrieve Sequential Data Space Entry P 
« Signal Exception 2) 


« Update Data Space Entry 
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1237 Operation Not Valid with Join Cursor 


An attempt has been made to insert, update, or delete a data space entry through a join cursor. 
Information Passed: 


e Cursor System pointer 
Instructions Causing Exception: 
¢ Copy-Data Space Entries 
« Delete Data Space Entry 
e Insert Data Space Entry 
e Insert Sequential Data Space Entries 
e Signal Exception 
e Update Data Space Entry 
1238 Derived Field Operation Error 


During derived field operations, one of a variety of derived field operational errors occurred. 
The field number designates the relative location of the field as specified when creating the 
cursor or data space index. Field number equal 1 is the first field in the field location. The field 
location is described by the field location exception data. 


The error type is identical with those for exception number hex 1201, conversion mapping error 
with the addition of: 


¢ Hex 000B = An attempt has been made to divide by zero on a fixéd-point divide operation. 


e Hex OOOE = An attempt has been made to divide by zero on a floating-point divide opera- 
tion. 


Information Passed: 


e Cursor (0 for operations System pointer 
not involving a cursor) 
e Index (derived key operations) System pointer 
e Join cursor ordinal positions Char(128) 
e Index data space number (binary Bin(2) 
0 for operations not involving 
the index) 
e Cursor data space number (binary Bin(2) 


0 for operations not involving 
the cursor) 


« Ordinal entry number Bin(4) 
e Buffer location type Char(1) 
Hex 01 Cursor intermediate buffer 


Hex 02 = Group-by intermediate buffer 


Hex 03 = Intermediate key buffer 
e Reserved Char(3) 
¢ Number of offending fields Bin(2) 
e Field data (repeated) Char(6) 
— Field number Bin(2) 
— Error type Char(2) 
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— Reserved Char(2) 


The ordinal entry number will contain a binary zero value if the exception occurs during inserts . 
of new entries into a data space or the error occurs while processing default values during a ai 
join operation. 


The ordinal entry number and data space number will contain a value of binary zero when the 
error occurs during group-by derived field operations. 


Instructions Causing Exception: 
e Apply Journal Changes 
¢ Copy Data Space Entries 
e Data Base Maintenance 
e Insert Data Space Entry 
e insert Sequential Data Space Entries 
e Materialize Cursor Attributes 
e Modify Data Space Index Attributes 
e Retrieve Data Space Entry 
e Retrieve Sequential Data Space Entry 
e Set Cursor 
e Signal Exception 
e Update Data Space Entry 

1239 Derived Field Operation Error During Build Index 


While creating or rebuilding a data space index, data space entries were encountered which wa 
resulted in derived field operational errors. The build, before terminating, found up to 20 
instances of these types of errors. The instruction is terminated. 


Even though multiple errors may have occurred on a data space entry, only the first occurrence 
per entry is reported. 


Information Passed: 


e Data space index (binary zeros System pointer 
if during index creation) 
e Number of error descriptions Bin(2) 
e Reserved Char(4) 
e Error description (repeated) Char(14) 
— Data space number Bin(2) 
— Ordinal entry number Bin(4) 
— Field number Bin(2) 
— Error type Char(2) 
— Field location Char(1) 


Hex 03 = Intermediate key buffer 


Unassigned values reserved 


— Reserved Char(3) ) 
The exception field definitions are the same as for the hex 1238 exception (derived field opera- 
tion error). 
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1241 
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Instructions Causing Exception: 
¢ Create Data space Index 
¢ Data Base Maintenance 
¢ Activate Cursor (over delayed maintenance index) 
e Insert Sequential Data Space Entries 
e¢ Signal Exception 
Invalid Entry Definition Table 


During validation of an entry definition table supplied at Create Data Space, Create Data Space 
Index or Create Cursor, an invalid field may be found. 


Information Passed 


Instructions Causing Exception: 


e Error type Char(2) 
— Invalid table offset Bit 1 
— Invalid field type Bit 2 
— Invalid field length Bit 3 
— Invalid field precision Bit 4 
— Invalid entry length Bit 5 
— Invalid default length Bit 6 
— Invalid default offset Bit 7 
— Invalid field allocation Bit 8 
— Invalid null type . Bitg9 
— Type/variable length mismatch Bit 10 
Invalid field modifier Bit 11 
Reserved area not zero Bit 12 
Reserved (binary zero) Bit 13-15 
e Data Space Number Bin(2) 
(0 for Create Data Space instruction) 
e DSE field number Bin(2) 
(O if error type is not field related) 
Instructions Causing Exception: 
e Create Cursor 
e Create Data Space 
« Create Data Space Index 
e Signal Exception 
ISV parameter value in runtime data pointer array not correct. 
Information Passed 
e Reason code Bin(2) 
e« Array element number Bin(2) 
« Create time type Bin(2) 
e Create time length Char(2) 
e Runtime type Bin(2) 
e Runtime length Char(2) 
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1242 Non-Unique Fanout on Unique Join 


1243 


On a Unique fanout join more than one record in the “join to” file that satisfied the relationship 


was encountered. 


Information Passed 


Data Space Number Bin(4) 
Ordinal # of candidate record (the first key Bin{4) 
match) 

Ordinal # of record identified as the Bin(4) 


duplicate key 


Instructions Causing Exception: 


e Set cursor 


* Retrieve Sequential 
DDAT had an error. 


An error was found in a DDAT. 


Information Passed 
¢ Error type Bin(2) 


01 — No valid template size 

02 — No valid number of DDATs 

03 — No valid reserved are 

04 -- No valid DDAT length 

05 — No valid format code 

06 — No valid date separator 

07 -- No valid time separator 

08 -- No valid time zone 

09 — No valid time zone, hour 

10 -- No valid time Zone, minute 

11 -- No valid calendar information 

12 —- No valid calendar, month 

13 - No valid calendar, year 

14 -- No valid century definition 

15 -- No valid century definition current century 
16 — No valid century definition century division 
17 - No valid calendar table offset 

18 —- No valid reserved area 

19 — No valid number of era table elements 
20 — No valid era origin date 

21 — No valid era name 

22 - No valid era reserved area 


23 — No valid number of calendar table elements 
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24 -- No valid calendar effective date 
29 -- No valid calendar type 


26 -- No valid calendar reserve area 


e DDAT number in error Bin(2) 
e Era number Bin(2) 
e Calender number Bin(2) 


Instructions Causing Exception: 
Parent index cannot be used to create new index 


The parent index referenced in the create index instruction is internally damaged. When the 
index was converted by the system on a previous release of the operating system, the concat- 
enated key within the index was improperly converted. 


Instructions Causing Exception: 
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16 Exception Management 


1607 


1602 


1603 


1604 


1605 


Exception Description Status Invalid 
The tested exception description was not in the deferred state. 
Instructions Causing Exception: 
¢« Test Exception 
* Signal Exception 
Exception State of Process Invalid 


An attempt was made to retrieve exception data or resignal an exception when the process is 
not in an exception handling state; that is, the process is not in an external program, internal 
entry point, or branch point exception handler. The re-signal option is valid only for an external 
exception handler. 


Instructions Causing Exception: 
¢ Signal Exception 
e Retrieve Exception Data 
Invalid Invocation Address 


The invocation address specified in the space/invocation pointer on the instruction did not repre- 
sent an existing program invocation. 


Information Passed: 

e Invocation pointer 
Instructions Causing Exception: 

e Return From Exception 

e Sense Exception Description 

¢« Signal Exception 

e Send Process Message 

e Cancel Invocations 
Retry/resume Invalid 


An attempt was made to either retry a failed instruction or resume at an instruction after the 
instruction that failed in an invocation were retry or resume is not allowed. 


Information Passed: 
e Invocation pointer 
Instruction causing the exception: 
e Return From Exception 
No inquiry message found for reply message 
An attempt was made to send a reply message for an inquiry message that does not exist. 
Instruction causing the exception: 


e Send Process Message 
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1A Lock State 
1A0? Invalid Lock State 


The lock enforcement rule or rules were violated when an attempt was made to access an 
object. 


Information Passed: 
e System pointer to the object 
Instructions Causing Exception: 
e All instructions that enforce the lock rules 
e Signal Exception 
1A0Q2 Lock Request Not Grantable 


The lock request cannot be granted immediately and neither the synchronous nor asynchronous 
wait option was specified. 


Information Passed: 
¢ Pointer to lock request template Space pointer 


e Failing request number Bin(2) 
(relative entry position) 


Instructions Causing Exception: 
e Lock Object 
e Signal Exception 
1A03 Invalid Unlock Request 
An attempt was made to unlock a lock state not held by the current requesting process. 


Information Passed: 


e Pointer to unlock request template Space pointer 
e Number of requests not unlocked Bin(2) 
e Request number (relative entry Bin(2) 


position for each lock not unlockegq) 
Instructions Causing Exception: 
e Unlock Object 
° Signal Exception 
1A04 Invalid Object Lock Transfer Request 


An attempt was made to transfer locks that were not heid by the transferring process, or the 
transfer lock request was not granted because the lock granting rules would have been violated. 


Information Passed: 


¢« Pointer to lock transfer request template Space pointer 
e Number of requests not transferred Bin(2) 
e Request number (relative entry Bin(2) 


position for each lock not transferred) 
Instructions Causing Exception: 
e Transfer Object Lock 


e Signal Exception 
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1A05 Invalid Space Location Unlocked 


An attempt was made to unlock a space location lock not held by the current requesting 


process. J 


Information Passed: 


e Space location process attempted Space pointer 
to unlock 
¢ Unlock request Char(‘) 


Instructions Causing Exception: 
« Unlock Space Location 


¢ Signal Exception 
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1E Machine Observation 


1E01 


Table 23-1. Erroneous D-Code !nstruction Field 


[Table 2-1. Erroneous D-Code Inaruatn Feld 
a 
[1 [code operator | The 0-Coxe operator fed ia nvalig 
[2] Type operand _——=SS~*d:CThe ype operand elds inva 
ee 
[4] Reference operand ___~| The reference operand is invalid 
[5 | Constant operand _~|The constant operand is invalid. 
[6 Tvecaton deta operand |The invocation delta operand is invalid. 
[8 [Conversion operand | The conversion operand is invalig. 


Program Not Observable .- 


The program observation functions were destroyed for the program referenced by the executing 
instruction. 


Information Passed: 

e Program system pointer 
Instructions Causing Exception: 

e¢ Materialize Instruction Attributes 

e¢ Materialize Invocation 

° Signal Exception 
Invocation Not Found 
An invocation matching the specified criteria was not found. 
Instructions Causing Exception: 

e Find Relative Invocation 

e Signal Exception 
Invalid D-Code Instruction 


The Debug Interpreter (DBGINT) MI instruction has detected an invalid field of a D-Code Instruc- 
tion. The instruction and field are identified in the information passed (described below). 


Information Passed: 
e Erroneous D-Code instruction Char(40) 


The erroneous D-Code instruction is formatted as a hexadecimal string. Each hexadecimal 
digit represents 4 bits. D-Code instructions occupy twenty bytes. 


¢ D-Code instruction index Bin(4) 


The D-Code instruction index is the index of the erroneous D-Code instruction in the D-Code 
instruction array. It is the value of the program counter (PC) register when the Debug Inter- 
preter MI instruction issued this exception. 


e Erroneous D-Code instruction field Bin(4) 


The erroneous D-Code instruction field is an integer code indicating which field of the 
D-Code instruction is in error. The table below associates codes with corresponding fields. 
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¢ Erroneous reference operand field BIN(4) 


The erroneous reference operand field is an integer code indicating which field of the refer- 
ence operand is in error. The table below associates codes with corresponding fields. 


Table 23-2. Erroneous Reference Operand Field 


(3 | Storage dass fold ———~—~*dsCThe storage class fed is invalid 
(4 [invocation detafeld___| The Invocation data felis nval@ 


¢ Erroneous constant operand field BIN(4) 


The erroneous constant operand field is an integer code indicating which field of the con- 
stant operand is in error. The table below associates codes with corresponding fields. 


Table 23-3. Erroneous Constant Operand Field 


a a 
3 Pinteger fois ——~SSCSCSCS*diCT val othe integer constant invalid 
[| Character ~The val ofthe Bit character constant i val 
ee 
6 [numeration eld |The valve of the enumeration constants inva 


1E04 DBGINT error 


The Debug Interpreter (DBGINT) MI instruction has detected an error. The instruction and error 
are identified in the information passed (described below). 


Information Passed: 
¢ Erroneous D-Code instruction Char(40) 


The erroneous D-Code instruction is formatted as a hexadecimal string. Each hexadecimal 
digit represents 4 bits. D-Code instructions occupy twenty bytes. 


¢ D-Code instruction index Bin(4) 


The D-Code instruction index is the index of the erroneous D-Code instruction in the D-Code 
instruction array. It is the value of the program counter (PC) register when the Debug Inter- 
preter MI instruction issued this exception. 


¢ Error field Bin(4) 


The table below associates codes with corresponding errors. 


Table 23-4 (Page 7? of 2). Error Field 


Error Field Explanation 
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| 
| 
| 
| 
| 
| 


Code 
1 
2 


| 


Table 23-4 (Page 2 of 2). Error Field 


Error Field 
Mark Pointer 
Storage class 
Results space 


Stack error 
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Explanation 

The Mark Pointer is invalid. 

The storage class is invalid. 

The results space is not large enough. 


A stack entry is in error. 


Conversion specified The conversion specified is invalid. 


1£05 DBGINT error 


An error occurred on the operation while executing the debug interpreter (DBGINT). 


Information Passed: 


¢ Operation field 


Bin(4) 


The table below associates codes with corresponding operations. 


Table 23-5. Opcode Field 


a 
a 
a 
a 
a reaterthan regatta 
a 
a 
a 
0 
a 
a 
ns 
Sera OOS 
ss negste OCOC—CSC“‘“SCSCSCS 
8 tip 
id erent 
a 


« Data Type field 


The table below associates codes with corresponding data types. 


Table 23-6 (Page 1 of 2). datatyp Field 


a 
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Table 23-6 (Page 2 of 2). datatyp Field | 


Code Data Type 


2 Char_16 


4 Card_16 

5 Card_32 

6 Int_16 

7 Int_32 

8 Real_32 
Ra 
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20 Machine Support 
‘? 2001 Diagnose 


An error or discrepancy was found when a Diagnose instruction was processed. 
Information Passed: 
« Space element to the subelement in the operand 2 object that was being processed 
« Data Bin(4) 


— Subidentifier unique to the Bin(2) 
requested function 


— Indicator of the pointer in Bin(2) 
Operand 2 that was being processed 


Instructions Causing Exception: 
e Diagnose 
« Signal Exception 
2002 Machine Check 


A machine malfunction affecting system-wide operation has been detected during execution of 
an instruction in this process. 


Information Passed: 


e Timestamp that gives the - Char(8) 
current value of the machine time-of-day clock. 
e Error code indicating nature of machine Char(2) 
& check. (This value is machine-dependent and is 
only defined in the machine service documentation.) 
e Reserved (binary 0) Char(6) 
e VLOG dump ID Char(8) 
¢« Error class Bin(2) 


The error class codes for the type of damage detected are as follows: 


Hex 0000 = Unspecified abnormal condition 
Hex 0002 = Logically invalid device sector 
Hex 0003 = Device failure 


e Auxiliary storage device indicator Bin(2) 


This field is defined for error classes hex 0002 and hex 0003. It is the OU number of the 
failing device or O for a main storage failure. 


e Reserved (binary 0) Char(100) 
Instructions Causing Exception: 
e Any instruction 
e Signal Exception 
2003 Function Check 
The executing instruction has failed unexpectedly during execution within the process. 
Information Passed: 
‘S 


« Timestamp giving the current value Char(8) 
of the machine time-of-day clock. 
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e Error code indicating the Char(2) 
nature of the function check. 
(This value is machine-dependent.) 


e Reserved (binary 0) Char(6) 
e VLOG dump !ID Char(8) 
e Error class Bin(2) 


The error class codes for the type of damage detected are as follows: 


Hex 0000 = Unspecified abnormal condition 
Hex 0002 = Logically invalid device sector 
Hex 0003 = Device failure 


¢ Auxiliary storage device indicator Bin(2) 


This field is defined for error classes hex 0002 and hex 0003. It is the OU number of the 
failing device or 0 for a main storage failure. 


e Reserved (binary 0) Char(100) 
Instructions Causing Exception: 
e Any instruction 


¢ Signal Exception 
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22 Object Access 
Cc 2201 Object Not Found 


An attempt to resolve addressability into a system pointer was not successful for one of the fol- 
lowing reasons: 


¢ The named object was not located in the context specified in the symbolic address or in any 
context referenced in the name resolution list. 


¢ An object with a corresponding name was found but the user profile(s) governing execution 
of the instruction did not have the authority required for resolution. 


Information Passed: 


e Object identification Char(32) 
— Object type Char(‘) 
— QObject subtype Char(1) 
— Object name Char(30) 

e Required authorization Char(2) 


Instructions Causing Exception: 
e« Any instruction that references an object through a system pointer 
e Signal Exception 
2202 Object Destroyed 
An attempt was made to reference an object that no longer exists or part of it no longer exists. 


This exception may not be signaled for operations which refer to the value of a space pointer 
= machine object, but which do not attempt to reference the space data the pointer addresses. 

This can also be signaled when an associated space of the object is missing. The following 

instructions may not signal this exception upon references to a space pointer machine object. 


e Add Space Pointer 

¢ Compare Pointer for Space Addressability 
¢ Compare Pointers for Equality 

e Compare Space Addressability 

¢ Set Space Pointer 

¢ Set Space Pointer with Displacement 

e Set Space Pointer from Pointer 

e Subtract Space Pointer Offset 

e Subtract Space Pointers For Offset 


See the particular instruction description for more detail. 
Instructions Causing Exception: 


e Any instruction that references an object through a system pointer, a space pointer, ora 
data pointer 


« Any instruction that references a scalar or a pointer operand when the object and the space 
containing the scalar or pointer have been destroyed 


¢ Signal Exception 
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24 Pointer Specification 


2401 


2402 


2403 


Pointer Does Not Exist 


A pointer reference was made to a storage location in a space that does not contain a pointer 
data object, or a reference was made to a space pointer machine object that was not set to 
address a space. 


This exception may not be signaled for operations which refer to the value of a space pointer 
machine object, but which do not attempt to reference the space data the pointer addresses. 
The following instructions may not signal this exception upon references to a space pointer 
machine object. 


e Add Space Pointer 

e Compare Pointer for Space Addressability 

e Compare Space Addressability 

e Set Space Pointer 

e Set Space Pointer With Displacement 

e Set Space Pointer from Pointer 

¢ Subtract Space Pointer Offset 
see the particular instruction description for more detail. 
Instructions Causing Exception: 

e Any instruction that has pointer operands 


e Any instruction that references a base operand (scalar or pointer) when the base pointer is 
not a space pointer 


e Any instruction that allows a scalar defined by a data pointer to be an operand 
e Any instruction that requires a pointer as part of the input template 
e Signal Exception 

Pointer Type Invalid 


An instruction has referenced a pointer object that contains an incorrect pointer type for the 
operation requested. 


Instructions Causing Exception: 
e Any instruction that has pointer operands 


e Any instruction that contains a base operand (scalar or pointer) when the base pointer is not 
a space pointer 


e Any instruction that allows a scalar defined by a data pointer to be an operand 
e Any instruction that requires a pointer as part of the input template 
e Signal Exception 

Pointer Addressing Invalid Object Type 


An instruction has referenced a system pointer that addresses an incorrect type of system object 
for this operation. 


Information Passed: 
e The invalid system pointer System pointer 


Instructions Causing Exception: 
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« Any instruction that references a system pointer, either as an operand or within a template 
operand, and that requires a specific object type as a part of its operation 


e Signal Exception 
2404 Pointer Not Resolved 


The operation did not find a resolved system pointer. For example, NRL (name resolution list) 
entries must be resolved system pointers that address contents. 


Information Passed: 

e The invalid pointer System pointer 
Instructions Causing Exception: 

e Resolve System Pointer 


e Any instruction that causes a system pointer to be implicitly resolved when the NRL is used 
in the resolution. All entries in the NRL must be resolved. 


« Resolve Data Pointer 


e Any instruction that causes a data pointer to be implicitly resolved. All activation entries in 
the process must contain a resolved pointer to the associated program. 


e Signal Exception 
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26 Process Management 
2602 Queue Full J 


An attempt was made to enqueue a message to a queue that is full and is not extendable. 
information Passed: 

e Queue for which the enqueue was attempted system pointer 
Instructions Causing Exception: 

¢ Enqueue 

¢ Request I/O 


e Signal Exception 
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2A Program Creation 


2A01 


2A02 


2A03 


2A04 


2A05 


2A06 


Program Header Invalid 
The data in the program header was invalid. 
Instructions Causing Exception: 
e Signal Exception 
ODT Syntax Error 
The syntax (bit setting) of an ODT (object definition table) entry was invalid. 
Information Passed: 
e ODT entry number Char(2) 
Instructions Causing Exception: 
e Signal Exception 
ODT Relational Error 
An ODT (object definition table) entry reference to another ODT entry was invalid or missing. 
Information Passed: 
e ODT entry number Char(2) 
Instructions Causing Exception: 
e Signal Exception 
Operation Code Invalid 
One of the following conditions occurred. 
e The operation code did not exist. 
e The optional form was not allowed. 
Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 
e Signal Exception 
Invalid Op Code Extender Field 
The branch/indicator options were invalid. 
Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 

e Signal Exception : 
Invalid Operand Type 
One of the following conditions was detected: 


e An operand was not the required type (signed immediate, immediate, constant data object, 
scalar data object, pointer data object, null, branch point, or instruction definition list). 


e An operand was described as an immediate or constant data object. However, the instruc- 
tion specifies that the operand be modified to something other than an immediate or con- 
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2A07 


2A08 
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stant data object, or the instruction does not allow an immediate or constant data object 
operand. 


e The operand type specified is not a valid operand type. 


e The type of one operand does not satisfy a required relationship with the type of another 
operand. 


Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 
e Signal Exception 
Invalid Operand Attribute 
One of the following conditions was detected: 


e An operand did not have the attributes required by the instruction (character, packed 
decimal, zoned decimal, binary, floating-point, scalar, array, assumed, overlay, restricted, 
open, based, explicitly based). 


¢ The attributes of one operand did not match the required attributes of another operand. 


e At least one operand in the argument list for a Transfer Control instruction was specified as 
automatic. 


e The receiver for an instruction specified with the optional round form has the floating-point 
attribute. 


Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 
e Signal Exception 
Invalid Operand Value Range 
One of the following conditions was detected: 


e An operand was a constant or immediate data object and was used as an index into an 
array or indicated a position in a character string, but it was outside the range of the array 
or character string. 


e An operand was a constant or immediate data object and did not conform to the value 
required by the instruction. 


e The operand immediate value is outside of the accepted range. The valid range for an 
unsigned immediate value is equal to or greater than O and less than or equal to 8191. The 
valid range for a signed immediate value is from negative 4096 through a positive 4095. 


Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 


e Signal Exception 
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2A09 Invalid Branch Target Operand 
One of the following conditions was detected: 


e An operand was not an instruction pointer, branch point, instruction number, or relative 
instruction number. 


e An operand was an instruction number or relative instruction number but was outside the 
range of the program. 


e A branch target operand identified an instruction that was not indicated as a branch target. 
Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 
e Signal Exception 
2A0A Invalid Operand Length 
One of the following conditions was detected: 


e The length attribute of an operand was not greater than or equal to the length required by 
the instruction. 


e The length attribute of an operand was invalid based on its relationship to the length attri- 
bute of another operand in the same instruction. 


e The length attribute of a decimal operand exceeds 15 digits when specified in conjunction 
with a floating-point operand. 


e A decimal operand has an invalid integer or fractional digit length in relationship to that 
required by the instruction. 


Information Passed: 


e {nstruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 
e Signal Exception 
2A0B Invalid Number of Operands 


The number of arguments in a Call Internal instruction was not equal to the number of parame- 
ters in the called entry point. 


Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 
¢ Signal Exception 
2A0C Invalid Operand ODT Reference 
The ODT reference was not within the range of the ODV. 
Information Passed: 


e Instruction number of the UBin(2) 
instruction being analyzed 


Instructions Causing Exception: 


e Signal Exception 
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2A0D Reserved Bits Are Not Zero 


The reserved bits in an opcode or operand are nonzero. 


Information Passed: 


Instruction number of the 
instruction being analyzed 


Instructions Causing Exception: 


Automatic storage for procedure exceeds maximum 


Signal Exception 
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UBin(2) 


The object was not created because an internal system limit was reached. Not enough auto- 
matic storage was available to allocate a data object within a procedure. 


Reduce the number or size of automatic data objects within the procedure. 


Information Passed: 


Current automatic storage offset 
Maximum automatic storage offset 
Data object size 

Data object dictionary index 

Data object dictionary entry information 
— Entry length 

— Entry 

Data object dictionary entry offset 
Procedure dictionary index 

Procedure dictionary entry information 
— Entry length 

— Entry 

Procedure dictionary entry offset 
Machine log note ID 


reserved 


Instructions Causing Exception: 


Machine automatic storage exceeds maximum 


Signal Exception 


UBin(4) 

UBin(4) 

UBin(4) 

UBin(4) 

Char(128) 

UBin(2) 

Char(*) 

UBin(4) t 
UBin(4) a 
Char(128) 

UBin(2) 

Char(*) 

UBin(4) 

Char(8) 

Char(8) 


The object was not created because an internal system limit was reached. Not enough machine 
automatic storage was available to allocate a data object within a procedure. 


Reduce the size and complexity of the procedure or reduce the level of optimization used to 
create the object. 


Information Passed: 


Current machine automatic storage offset 


Maximum machine automatic storage offset 


Data object size 
Data object dictionary index 


Data object dictionary entry information 


UBin(4) 
UBin(4) 


UBin(4) 
UBin(4) o 
Char(128) 
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— Entry length UBin(2) 
— Entry Char(") 

* Data object dictionary entry offset UBin(4) 

¢ Procedure dictionary index UBin(4) 

e Procedure dictionary entry information Char(128) 
— Entry length UBin(2) 
— Entry Char(*) 

e Procedure dictionary entry offset UBin(4) 

e Machine log note ID Char(8) 

* reserved Char(8) 


Instructions Causing Exception: 
e« Signal Exception 
2A1f2 Data type or length of initial value not valid 


The object was not created because an initialization table entry is not valid. An initial value for 
a data object has either a data type that is not valid or a length that is not valid. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 


¢ Initial value data type * UBin(4) 
¢ Initial value length UBin(4) 
¢ Initialization table index UBin(4) 

— Entry length UBin(2) 

— Entry Char(*) 
e Initialization table entry offset UBin(4) 
« Machine log note ID Char(8) 
e reserved Char(8) 


Instructions Causing Exception: 
e Signal Exception 
2A14 Static data initialized to address of automatic data 


The object was not created because an initialization table entry is not valid. The static data 
cannot be initialized to the address of automatic data. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| e Initialization table entry information Char(128) 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| Information Passed: 
| 
| 
| 
| 
| 
| 


¢ Initialization table index UBin(4) 

e Initialization table entry information Char(128) 
— Entry length UBin(2) 
— Entry Char(*) 

e Initialization table entry offset UBin(4) 

e Static data dictionary index UBin{4) 
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¢ Static data dictionary entry information Char(128) 
— Entry length UBin(2) 
— Entry Char(*) 

e Static data dictionary entry offset UBin(4) 

« Automatic data dictionary index UBin(4) 

« Automatic data dictionary entry information Char(128) 
— Entry length UBin(2) 
— Entry Char(*) 

e Automatic data dictionary entry offset UBin(4) 

e Machine log note ID Char(8) 

¢ reserved Char(8) 


Instructions Causing Exception: 


¢ Signal Exception 


Initial value for static data not valid 


The object was not created because an initialization table entry is not valid. Static data is initial- 
ized, but the initial value is not valid. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 


e Reason code UBin(4) 

{= Reserved initialization entry not binary Zeros. 

2= Initial length specified when zero is expected. 

3 = Target of initialization is too small. 

4= Procedure not target of initCodeAddress. 

5 = PEP specified as target of initCodeAddress. 

5 = Offset specified when zero is expected. 

{= Rep specified when zero is expected. 

8 = Bitfield initialization was not terminated by entry with dictNo=0. 

9 = Bitfield length is not a valid value. 

10 = Length is not large enough to initialize bitfield. 

11 = A dictionary entry (or its owner) did not have TOBEMAPD = TRUE. 

12 = Attempt made to initialize storage with invalid storage class. 

13 = Invalid dictionary index. 

14 = Invalid target dictionary index. 

15 = Target of initialized space pointer does not specify addr_taken. 
¢ Initialization table index UBin(4) 
e Initialization table entry information Char(128) 

— Entry length UBin(2) 

— Entry Char(*) 
e Initialization table entry offset UBin(4) 
e Machine log note ID Char(8) 
e reserved Char(8) 


Instructions Causing Exception: 


e Signal Exception 
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The object was not created because an internal system limit was reached. The number of pro- 
cedures exceeds the maximum allowed. 


Reduce the number of procedures. 


Information Passed: 


Maximum procedures 

Procedure dictionary index 

Procedure dictionary entry information 
— Entry length 

— Entry 

Procedure dictionary entry offset 
Machine log note ID 


reserved 


Instructions Causing Exception: 


Signal Exception 


2A17 Type table entry not valid 


UBin(4) 
UBin(4) 
Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
Char(8) 
Char(8) 


The object was not created because the type table contains an entry that is not valid. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 


Reason code 


1 = Length of data object is invalid. 
2= Type of data object is invalid. 

3 = Bit field displacement is invalid. 
4= Bit field width is invalid. 

5 = Reserved area is invalid. 


Type table index 

Type table entry information 
— Entry length 

— Entry 

Type table entry offset 
Machine log note ID 


reserved 


Instructions Causing Exception: 


Signal Exception 


2A18 Alias table entry not valid 


The object was not created because the alias table contains an entry that is not valid. 


UBin(4) 


UBin(4) 
Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
Char(8) 
Char(8) 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 


Reason code 


1 = Record type of alias table entry is invalid. 


UBin(4) 
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| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


= Invalid alias class td. 
= Invalid alias class size. 
= Invalid dictionary id. 


= Invalid alias union id. 
= Invalid alias union size. 
Invalid class id. 


OOonnnarb wn 
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Alias table entry information 
— Entry length 

— Entry 

Alias table entry offset 
Machine log note ID 


reserved 


Instructions Causing Exception: 


Signal Exception 


2A19 Size of constants exceeds maximum 


= Reserved field in alias class not binary zeros. 


= Dictionary id is not for a data object. 
= Reserved field in alias union not binary zeros. 
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Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
Char(8) 
Char(8) 


The object was not created because an internal system limit was reached. Not enough space 


was available to add a constant within a procedure. 


Reduce the number or size of constants within the procedure. 


Information Passed: 


Current size of all constants 
Maximum size of all constants 
Constant size 

Constant dictionary index 

Constant dictionary entry information 
— Entry length 

— Entry 

Constant dictionary entry offset 
Procedure dictionary index 
Procedure dictionary entry information 
— Entry length 

— Entry 

Procedure dictionary entry offset 
Machine log note ID 


reserved 


Instructions Causing Exception: 


Signal Exception 


2A1A Procedure size exceeds maximum 


UBin(4) 
UBin(4) 
UBin(4) 
UBin(4) 
Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
UBin(4) 
Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
Char(8) 
Char(8) 


The object was not created because an internal system limit was reached. Not enough space 
was available for a procedure. 


Chapter 23. Exception Specifications 23-75 


Hex 2A, Program Creation Exceptions 


Reduce the size of the procedure. 


Information Passed: 


Maximum procedure size UBin(4) 
Procedure dictionary index UBin(4) 
Procedure dictionary entry information Char(128) 
— Entry length U Bin(2) 
— Entry Char(*) 
Procedure dictionary entry offset UBin(4) 
Machine log note ID Char(8) 
reserved Char(8) 


Instructions Causing Exception: 


e Signal Exception 


2A1B Instruction stream not valid 


The object was not created because the sequence of instruction stream objects is not valid. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 


e Reason code UBin(4) 

1= Undefined MI operation code. 

2= Invalid type table index. 

3 = Invalid dictionary number. 

4= Invalid label identifier. 

5 = One or more instructions are out of sequence. Typically signaled when the first 
instruction in a procedure is not ENT. 

6 = The dictionary id on the END instruction does not match the dictionary id on first 
ENT instruction in the current procedure. 

C= An operand of a an MI instruction has has an invalid value. 

§ = The data type of the stack operand(s) is invalid for the operation being attempted. 

g9 = The length of the stack operand(s) is invalid for the operation being attempted. 

10 = An operand of a load instruction has has an invalid data type. 

1= An object which is loaded has scope greater than the current procedure’s scope. 

12 = The target of a STR operation in the new MI instruction stream is not a variable, or 
the target is a register variable and either offset or typeNo are nonzero. 

13 = The MI value stack is not empty at a label, jump, or other point in the instruction 
stream at which the MI architecture asserts it must. 

14 = The MI value stack has fewer items on it than need to be popped. 

15 = The values retrieved from the MI value stack are not compatible. 

16 = The data type of the stack operands is invalid for the comparison being attempted, 
(i.e. UNORD on binary dt). 

17 = There is control flow in the NMI program which reaches either a secondary entry 
point or an END instruction. 

18 = No exception handlers are currently enabled when a DHNDLR is encountered. 

19 = A DHNDLR instruction specifies an exception handler that was not the last one 
enabled. 

20 = A LAB instruction was encountered where the label qualifier was not one of: 
FwdOnlyLabe! (1) or GeneralLabel (2). 

21 = An object in the dictionary with the “is_reg” attribute lacks one or more of the 


required characteristics for inclusion in the machine storage class. For example, 
the dictionary object is the target of a LDA operation, or the dictionary object has 
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its data type or length superseded with a type table entry on a load or store opera- 
tion. 


22 = A‘blocked built-in function is called. 

23 = An invalid built-in function number in CALLBI instruction. 2) 

24 = An invalid alias union id in PALI instruction. 

25 = An invalid pali flag in PALI instruction. 

26 = A switch-specific operation (i.e. CASE, DEFAULT, BRK, ENDS) was encountered 
outside of a SWE-ENDS block. 

2f/ = Two CASE ranges were found with one or more elements in common, violating the 
requirement that all CASE ranges be totally disjoint. 

28 = The low selector value for the range of a CASE statement is greater than the high 
selector value. 

29 = A second DEFAULT case was found for a switch statement in the instruction 
stream. 

30 = Built-in OPMPARMADDR or OPMPARMCNT is not invoked from PEP. 

31 = A required built-in function argument was not specified. 

35 = The number of arguments specified for a built-in function is incorrect. 

36 = The null op mask specifies an argument that is not valid. 

37 = A switch statement is still active (i.e. the ENDS operation for an open switch has 
not been encountered) at the END of a procedure. 

38 = All three labels on a MiCMPB operation were found to equal zero. 

39 = Buit-in function NPMPARMLISTADDR was invoked from PEP. 

40 = A label that was the target of a jump (FJP,TJP,CMPB,UJP) was not found in the 
instruction stream. 

41 = A label that is in the dictionary, and that is indicated therein to have had its 
address taken, was not found in the instruction stream. 

42 = A label constant on the stack when IJMP was encountered was now owned by the f 
current procedure being translated. J 

43 = A data object which has been allocated to a machine storage class is the target of 
a LDA instruction, has its address referenced from the initialization component, or 
is used as an exception handler communication area. This situation can occur if 
the front end did not set the addr_taken flag for the data object (or for the data 
object’s owner if it is the member of a aggregate). 

Current instruction count UBin(4) 

Data offset UBin(4) 

Current instruction offset UBin(4) 

Current instruction opcode UBin(4) 

Current statement number UBin(4) 

Machine log note ID Char(8) 

reserved Char(8) 


Instructions Causing Exception: 


e Signal Exception 


2A1C Size of literals exceeds maximum 


The object was not created because an internal system limit was reached. Not enough space 
was available in the literal pool to add the literal. 


Reduce the number or size of literals. 


Information Passed: 


¢ Current size of ali literals UBin(4) 


Maximum size of all literals UBin(4) 
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Literal size 


Literal information 


— Literal length 


Literal 


Machine log note ID 


reserved 


Instructions Causing Exception: 


° Signal Exception 


2A1D Dictionary entry not valid 
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UBin(4) 
Char(128) 
UBin(2) 
Char(*) 
Char(8) 
Char(8) 


The object was not created because the dictionary contains an entry that is not valid. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 


e Reason code 


Hoi i Ww ue ued 


Undefined data type. 
Invalid reserved entry. 


Parent of data object is IsReg variable. 


Invalid alias union number. 
Invalid alignment. 

Invalid data type. 

Invalid flags. 

Invalid flags2. 

Invalid handler. 

Invalid handler comm area. 
Invalid handler level. 
Invalid handler type. 
Invalid length. 

Invalid linkage. 

Invalid literal type. 

Invalid offset. 

Invalid owner. 

Invalid procedure type. 
Invalid replication. 

Invalid reserved1. 

Invalid reserved2. 

Invalid reserved3. 

Invalid return length. 
Invalid return type. 

Invalid scope. 

Invalid storage class. 
Invalid extended description. 
Invalid control action. 


e Dictionary index 


¢ Dictionary entry information 


Entry length 


Entry 


Dictionary entry offset 


Machine log note !D 


UBin(4) 


UBin(4) 
Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
Char(8) 
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* reserved 
Instructions Causing Exception: 
e Signal Exception 


Level of machine interface not supported on target release 


Char(8) 


The object was not created because the software release level of the machine interface that was 


used is not compatible with the software release level targeted. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 
¢ Machine interface level used 
e Machine interface level targeted 
e Machine log note ID 
* reserved 
Instructions Causing Exception: 
¢ Signal Exception 


Size of dictionary exceeds maximum 


UBin(2) 
UBin(2) 
Char(8) 
Char(8) 


The object was not created because an internal system limit was reached. Not enough space 


was available in the dictionary. 


Reduce the size and complexity of the procedure or reduce the level of optimization used to 


create the object. 
Information Passed: 
e Procedure dictionary index 
e Procedure dictionary entry information 
— Entry length 
— Entry 
e Procedure dictionary entry offset 
e Machine log note ID 
°* reserved 
Instructions Causing Exception: 
* Signal Exception 


internal machine operation not valid 


UBin(4) J 


Char(128) 
UBin(2) 
Char(*) 
UBin(4) 
Char(8) 
Char(8) 


The object was not created because the internal representation of a machine operation is not 


valid. The machine interface template probably contains an error. 


There is a problem in the compiler. Report this problem to the supplier of the compiler. 


Information Passed: 
e Name of machine operation 
e Statement number 
e Machine log note ID 
e reserved 
Instructions Causing Exception: 


¢« Signal Exception 


Char(15) 
UBin(4) 
Char(8) 


Char(8) ») 
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| 2A2? Size of internal binding table exceeds maximum 


The object was not created because an internal system limit was reached. Not enough space 
was available in an internal binding table. 


Reduce the number of external data objects in the program. 


Information Passed: 


¢ Current identifier UBin(4) 
« Maximum identifier UBin(4) 
e Machine log note !D Char(8) 
* reserved Char(8) 


Instructions Causing Exception: 
e Signal Exception 
2ASE An error was detected in a static storage definition or initialization. 


An attempt was made to declare a static variable larger than the maximum size, or initialize a 
static variable beyond its defined Jength. 


Correct the invalid initialization. 
Information Passed: 
e Reason code UBin(2) 
e VLIC log note ID . Char(8) 
Instructions Causing Exception: 


¢ Signal Exception 


Two initialization entries within the initialization component are for the same storage location. 
Contact your service representative to report the problem. 
Instructions Causing Exception: 
¢ Signal Exception 
2A60 Dictionary ID is not valid. 


A dictionary ID specified on one of the binding messages generated by the optimizing translator 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 2A5F Overlapping initializations not valid. 

| 

| 

| 

| 

| 

| 

| was not valid. 

| Contact your service representative to report the problem. 
| information Passed: 

| e Dictionary |D UBin(4) 
| e Reason code UBin(2) 
| Instructions Causing Exception: 

| e Signal Exception 

| 2A61 Binding specification value not valid. 
| A value within the binding specifications component was in error. 
| Contact your service representative to report the problem. 
| Information Passed: 

| 


e Offset of error UBin(4) 
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2A63 


2AA0 


2AB0 
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e Length of error 

e Reason code 
Instructions Causing Exception: 

e Signal Exception 
Copyright component value not valid. 
A value within the copyright component was in error. 
Contact your service representative to report the problem. 
Information Passed: 

e Offset of error 

¢ Length of error 

e Reason code 
Instructions Causing Exception: 

e Signal Exception 
Module limitation exceeded. 
An internal part of the module exceeds allowed size. 
Contact your service representative to report the problem. 
Information Passed: 

« Reason code 
Instructions Causing Exception: 

e Signal Exception 


Attempt to delete part that may not be deleted. 


UBin(2) 
UBin(2) 


UBin(4) 
UBin(2) 
UBin(2) 


“UBin(2) 


The module was created with observable data that may not be deleted. An attempt was made 


to delete that data. 
Contact your service representative to report the problem. 
Information Passed: 
e Reason code 
Instructions Causing Exception: 
Object list referential extension not valid. 
An entry in the object list was not valid. 
Contact your service representative to report the problem. 
Information Passed: 
e Pointer to the object list 
¢« Byte offset 
e Entry index 
e Field length 
e Bit offset 
e Reason code 


Instructions Causing Exception: 


UBin(4) 


System pointer 
UBin(4) 
UBin(4) 
UBin(4) 
UBin(2) 
UBin(2) 
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Symbol resolution list referential extension not valid. 


An entry in the symbol resolution list was not valid. 


Contact your service representative to report the problem. 


Information Passed: 

e Pointer to the symboi resolution list 

° Byte offset 

e Entry index 

e Field length 

e Bit offset 

*« Reason code 
Instructions Causing Exception: 
Service program export list referential extension not valid. 
An entry in the service program export list was not valid. 
Contact your service representative to report the problem. 
Information Passed: 

¢ Pointer to the service program export list 

e Byte offset 

e Entry index 

e Field length 

° Bit offset 

e Reason code 


Instructions Causing Exception: 


Secondary associated spaces list referential extension not valid. 


An entry in the secondary associated spaces list was not valid 


Contact your service representative to report the problem. 
Information Passed: 
e Pointer to the secondaray associated spaces list 
e Byte offset 
e Entry index 
e Field length 
e Bit offset 
e Reason code 
Instructions Causing Exception: 
Program limitation exceeded. 


An internal part of the program exceeds allowed size. 


Contact your service representative to report the problem. 


Information Passed: 


¢ Reason code 


System 
UBin(4) 
UBin(4) 
UBin(4) 
UBin(2) 
UBin(2) 


System 
UBin(4) 


" UBin(4) 


UBin(4) 
UBin(2) 
UBin(2) 


System 
UBin(4) 
UBin(4) 
UBin(4) 
UBin(2) 
UBin(2) 


UBin(2) 
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Instructions Causing Exception: 
2ACO Attempt to delete part that may not be deleted. J 


The program was created with observable data that may not be deleted. An attempt was made 
to delete that data. ” 


Contact your service representative to report the problem. 
Information Passed: 
e Reason code UBin(4) 


Instructions Causing Exception: 
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2C Program Execution 


2C07 


2C02 


2C04 


2C05 


Return Instruction Invalid 


Improper usage of the Return, Transfer Control, or Return From Exception instruction occurred 
for one of the following reasons: 


e A Return From Exception instruction was executed in an invocation that was not defined as 
an exception handler. 


e A Return External or Transfer Control instruction was issued from a first-invocation-level 
exception handler. 


e A Transfer Control instruction was issued from a first-invocation-level event handler. 
Instructions Causing Exception: 

e Return External 

e Return From Exception 

e Transfer Control 

e Signal Exception 
Return Point Invalid 


An attempt was made to use a Return External instruction with a return point that was invalid for 
one of the following reasons: 


¢ The return point value was outside the range of the return list specified on the preceding 
Call External instruction. 


e A nonzero return point was supplied, but no return list was supplied on the preceding Call 
External instruction. 


e A nonzero return point was supplied when a Return External instruction was issued in the 
first invocation in the process. 


e A nonzero return point was supplied when the Return External instruction was issued by an 
invocation acting as an event handler. 


Instructions Causing Exception: 
e Return External 
e Signal Exception 

<D> 

Branch Target Invalid 


An attempt was made to branch to an instruction defined through an instruction pointer, but the 
instruction pointer was set by a program other than the one that issued the branch. 


Information Passed: 
e Instruction pointer causing the exception 
Instructions Causing Exception: 
e All instructions that have a branch form 
e Signal Exception 
Activation in Use by Invocation 


An attempt was made to de-activate a program that has an existing invocation which is not the 
invocation issuing the instruction. 


Information Passed: 


Chapter 23. Exception Specifications 23-84 


2C08 


2C10 


2C11 


2C12 


2C13 


Hex 2C, Program Execution Exceptions 


e Program system pointer 

Instructions Causing Exception: 
° De-activate Program Jo 
e Signal Exception 

Branch target defined by label pointer not valid 


The program that was running attempted to branch to a label pointer which points to a label 
than is not in the current procedure. 


Change the program so that it only branches to a label in the currently running procedure. 
Information Passed: 

e Branch target Label pointer 
Instructions Causing Exception: 

¢« Signal Exception 
Process object destroyed 
The process object pointer refers to a process object which has been destroyed. 
Information Passed: 
None. 
Instructions Causing Exception 

e Any instruction which has process object pointer operands. 
Process object access invalid 


An attempt has been made to reference a process object from another process which is not the 4 
owner of that object. oe 


Information Passed: 
None. 
Instructions Causing Exception 
e Any instruction which has process object pointer operands may signal this exception. 
Activation group access violation 


An inter-activation group access is not permitted based on the activation group access pro- 
tection mechanism. 


Information Passed: 

e Source activation group mark UBin(4) 

¢ Target activation group mark UBin(4) 
Instructions Causing Exception 

¢ Materialize Activation Attributes 

¢ Materialize Invocation Attributes 

e Cancel Invocation 

¢ other instructions which use the activation group access protection mechanism. 
Activation group not found 


The activation group specified by an activation group identifier could not be found in the P) 
process. The activation group was either destroyed or never existed. 


Information Passed: 
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2C15 


2C 16 


2C17 
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e activation group number UBin(4) 
Instructions Causing Exception: 

e Destroy Activation Group 

e Materialize Activation Group Attributes 

e Materialize Heap Space Attributes 
Activation group in use 
The specified activation group contains an invocation {i.e., it is in use) and cannot be destroyed. 
Information Passed: 

e activation group number UBin(4) 
Instructions Causing Exception: 

¢ Destroy Activation Group 
Invalid operation for program 


The operation requested is not supported for this model of program. The system supports two 
distinct “models” of program objects. Not all operations are supported for all models of pro- 
grams. (E.g., a new model program object cannot be deactivated.) 


Information Passed: 

e Program System pointer 
Instructions Causing Exception 

¢« deactivate program 

¢ call program 

e create bound program 
Program activation not found 


The activation specified by an activation mark value does not exist. It was either destroyed or 
never created. 


Information Passed: 

¢« Activation mark Bin(4) 
Instructions Causing Exception: 

¢ Materialize Activation Attributes 
Default activation group not destroyed 


An attempt was made to destroy a defauit activation group using the Destroy Activation Group 
instruction. The operation is not permitted. 


Information Passed: 

e none ‘ 
Instructions Causing Exception: 

¢ Destroy Activation Group 
Invalid source invocation 


A source invocation was specified that is older than the target invocation. The operation is not 
permitted. 


Information Passed: 
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source invocation offset Bin(2) 

Operand number Bin(2) . 
Reserved (zeros) Char(10) J 
Base invocation used to determine source Invocation pointer 


Instructions Causing Exception: 


send Process Message 
Materialize Process Message 
Modify Process Message 


Cancel Invocations 


Invalid origin invocation 


An origin invocation was specified that is older than the source or target invocation. The opera- 
tion is not permitted. 


Information Passed: 


Origin invocation offset Bin(4) 
Operand number Bin(2) 
Reserved (zeros) Char(10) 


Base invocation used to determine origin Invocation pointer 


Instructions Causing Exception: 


send Process Message 
Materialize Process Message Jo 
Modify Process Message | 
Cancel Invocations 

Materialize Invocation Attributes 

Modify Invocation Attributes 


Invocation offset outside range of current stack 


An offset was specified that attempts to identify an invocation that is either newer than the 
newest invocation in the process or older than the oldest invocation in the process. The opera- 
tion is not permitted. 


Information Passed: 


Length of invocation identification Bin(2) 
Bit offset to invalid field Bin(2) 
Operand number Bin(2) 
Reserved (zeros) Char(10) 
Invocation identification value Char(*) 


Instructions Causing Exception: 


Send Process Message 
Materialize Process Message 
Modify Process Message a 


Cancel Invocations 
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e« Materialize Invocation Attributes 

+ Modify Invocation Attributes 

e Find Relative Invocation 

e Sense Exception Description 
Invocation not eligible for operation 


An operation was attempted that is not valid for the specified invocation. The operation is not 
permitted. 


Information Passed: 

* none 
Instructions Causing Exception: 

¢« Modify Invocation Attributes 
Instruction not valid for invocation type 


An attempt was made to reference an invocation with an instruction that is not valid for the type 
of the invocation. The operation is not permitted. 


Information Passed: 

e none 
Instructions Causing Exception: 

e Materialize Invocation 

e Materialize Instruction Attributes 
automatic storage overflow 


The automatic storage for the specified activation group has been exhausted. Further program 
execution within the activation group is not possible. 


Information Passed: 

° activation group mark UBin(4) 
Instructions Causing Exception: 

* program call instructions 

e procedure call instructions 

« Modify Automatic Storage Allocation 
activation access violation 


The program could not be activated within an existing activation group. The program specifies 
an activation group access protection level which is incompatible with the existing activation 
group. 


Information Passed: 
e Program System pointer 
¢« Target activation group mark UBin(4) 
Instructions Causing Exception: 


e program call instructions 


2C1F program signature violation 


The source program specifies a signature which is not supported by the service program. The 
service program interface has changed and the source program must be rebound. 
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Information Passed: 
* Source program 
« Service program 
e Signature 
Instructions Causing Exception: 
e¢ program call instructions 


Static storage overflow 
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system pointer 
system pointer 
Char(16) 


The static storage allocation for an activation group has been exceeded. 


Information Passed: 
e Activation group mark 
Instructions Causing Exception: 
° program call instructions 


program import invalid 


UBin(4) 


The actual type of a service program export does not agree with the type expected by a client 


program. 
Information Passed: 

e« Client program 

e Service program 

e Export-ID 

e Expected type 

e Actual type 
The type is encoded as: 


0001 procedure 
0002 = data 


Instructions Causing Exception: 


* program call instructions 


data reference invalid 


System pointer 


“ System pointer 


UBin(4) 
UBin(2) 
UBin(2) 


The client program imports a data item from a program which is active in a different activation 
group. Data items cannot be refernced across activation group boundaries. 


Information Passed: 
e Client program 
e Service program 


e Export-ID 


e Client activation group mark 


e Service activation group mark 


Instructions Causing Exception: 


e program call instructions 


System pointer 
System pointer 
UBin(4) 
UBin(4) 
UBin(4) 
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2C23 


2024 


2025 


Hex 2C, Program Execution Exceptions 


imported object invalid 
The source program attempts to import items from an object which is not a service program. 
Information Passed: 

e Source program System pointer 

e Qbject system pointer 
Instructions Causing Exception: 

¢ program call instructions 
activation group export conflict 


The activation of one or more programs has resulted in conflicting specifications for activation 
group exports. 


Information Passed: 


e Reason UBin(4) 
e Activation group mark UBin(4) 
e Name (first 64 characters) Char(64) 


The Reason field supplies more information as follows: 


1 = multiple strong exports of the specified item were encountered. 


2 = the specified item was already allocated within the activation group — a subsequent 
strong export was encountered for the same item. ‘ 


3 = the specified item was already allocated within the activation group — a subsequent 
weak export with a conflciting length specification was encountered. 


Instructions Causing Exception: 
¢ program call instructions 
import not found 


The client program specifies a procedure or data import which is not found in the service 
program. The export-/D specified in the client program exceeds the export count of the service 
program. The client program must be rebound. 


Information Passed: 


e Client program system pointer 
e Service program System pointer 
¢ Export-ID UBin(4) 
e Export count UBin(4) 


Instructions Causing Exception: 


e program call instructions 
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2E Resource Control! Limit 
2E01 User Profile Storage Limit Exceeded 
The user profile specified insufficient auxiliary storage to create or extend a permanent object. 
Information Passed: 
e« User profile System pointer 
Instructions Causing Exception: 
« All create instructions creating a permanent object 
e All instructions extending a permanent object 


Any instruction which references bytes of data within a space object can cause an automatic 
extension of the space if the space has the attribute of being automatically extendible. 
Therefore, this exception may be signaled for any instruction which has an operand which 
references bytes of data in a space. 


e Signal Exception 
2E02 Security audit journal failure 
An entry could not be sent to the security audit journal. 


Information Passed: 


e Audit journal port System pointer 

e Object being journaled ‘System pointer 
(null for program adopt audits) 

e Return code Char(2) 


hex 0000 - No error detected 

hex 0001 - No journal space attached 

hex 0002 - Extend failure 

hex 0003 - Damaged journal port 

hex 0004 - Damaged journal space 

hex 0005 - Maximum sequence number 
hex 0006 - Journal failure 

hex 0008 - Journal space off line 

hex 0009 - Journal port off line 

hex 0100 - This object type is not to be audited 
hex 0200 - Invalid data length 

hex 0300 - Object type table not defined 
hex FFOO - Failure in VLIC auditing module 


Instructions Causing Exception: 


e All instructions performing underlying operations that cause an audit record to be sent 
(program adopt, object change or reference, etc.). 
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32 Scalar Specification 


3201 


3202 


3203 


Scalar Type Invalid 


A scalar operand did not have the following data types required by the instruction: 


Character 
Packed decimal 
Zoned decimal 
Binary 


Floating-point 


Instructions Causing Exception: 


Any instruction using a late bound (data pointer) scalar operand 


e Signal Exception 


Scalar Attributes Invalid 


A scalar operand did not have the following attributes required by the instruction: 


Length 
Precision 


Boundary 


Instructions Causing Exception: 


e Any instruction using a late-bound (data pointer) scalar operand 


e Any instruction that verifies the length of a character scalar in a space object operand 


Signal Exception 


Scalar Value Invalid 


A scalar operand does not contain a correct value as required by the instruction. 


Information Passed: 


Length of data passed Bin(2) 
Bit offset to invalid field (relative to 0) Bin(2) 
Operand number Bin(2) 
Invalid data Char(*) 


Instructions Causing Exception: 


e Any instruction using a scalar operand 


Signal Exception 
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36 Space Management 


3607 


3602 


Space Extension/Truncation J 


A Modify Space Attributes instruction made one of the following invalid attempts to modify the 
size of the space: 


*« Truncate the space to a negative size. 
e« Extend or truncate a fixed size space. 
« Extend a space beyond the space allowed in the referenced object. 


e An operation which required an automatic extension of a space occurred when the extended 
space would not fit in the access group which contained it. 


e Extend or truncate a space that has a hardware storage protection level of 01 or greater 
while running in user state. 


For information on the maximum size space allowed for a particular object, refer to the Limita- 
tions topic within the definition of the create instruction for that type of object. 


Information Passed 
e Space System pointer 
Instructions Causing Exception 
e Activate Program 
e Call External 
e Modify Automatic Storage Allocation 
e Modify Space Attributes 
¢ Signal Exception J 
e Transfer Control 


e Any instruction that invokes an external exception handler or an external event handler or 
an invocation exit 


e Any instruction which has an operand which references bytes of data in a space. 


Any instruction which references bytes of data within a space object can cause an automatic 
extension of the space if the space has the attribute of being automatically extendible. 


Invalid Space Modification 


A Modify Space Attributes instruction made an attempt to modify the attributes of a space but 
the requested modification is invalid. 


Information Passed: 
e System pointer to the object 
e Error code Char(2) 
Error codes and their meanings are as follows: 
Code Meaning 


0001 An attempt was made to modify the performance class attribute of the system 
object containing the space and the space was not a fixed length of size zero. 


0002 An attempt was made to modify a system object to or from the state of having a 
fixed length space of size zero and the operation is invalid for that type of system | 


object. 
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0003 An attempt was made to modify a system object to the state of having a fixed 
length space and the automatic extend attribute. These are mutually exclusive. 

0004 An attempt was made to modify the associated space of a program while running 
in user state on a system running at security level 40 or above. This combination 
is invalid. 


Instructions Causing Exception: 
¢ Modify Space Attributes 


e Signal Exception 
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38 Template Specification 


3801 


Template Value.invalid - : 
A template did not contain a correct value required by the instruction. J 
Information Passed: 

e Addressability to the template Space pointer 

e Offset to invalid field in bytes Bin(2) 


A value of 0 is the first byte in the template. An invalid field is considered to be the lowest- 
level character or numeric template entry that contains the information that is in error. 


e Bit offset in invalid field or 0 Bin(2) 
A 0 value indicates the leftmost bit in the invalid field. 

e The number of bytes in the invalid field Bin(2) 

e Instruction operand number Bin(2) 


(The first operand in an instruction is 1.) 
e Reason code Char(2) 


The meaning of the reason code which may or may not be returned is specific to the defi- 
nition of each instruction. Refer to the instruction definition to find out whether or not a 
meaningful value is returned. Unless otherwise stated, this field has no meaning. 


The following instructions support setting the reason code. 
— Create Dictionary 
— Create Module 
— Create Bound Program - 
Instructions Causing Exception: 
e Any instruction that has a space pointer as a source operand 
e Convert BSC to Character 
e Convert Character to BSC 
e Convert Character to MRJE 
e Convert MRJE to Character 
e Signal Exception 


¢ Scan with Control 


3802 Template Size Invalid 


3803 


A source template was not large enough for this instruction. 
Information Passed: 
e Addressability to the template Space pointer 
Instructions Causing Exception: 
e Any instruction that has a space pointer that addresses a source template operand 
e Signal Exception 
Materialization Length Exception 


Less than 8 bytes was specified to be available in the receiver operand of a materialize instruc- , 
tion. 


Instructions Causing Exception: 
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e¢ Any materialize instruction 
e Any retrieve instruction 


° Signal Exception 
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3A Wait Time-Out 


3A01 


3A02 


3A04 


Dequeue | 
A specified time period elapsed, and a Dequeue instruction was not satisfied. 
Information Passed: 

e The queue waited for System pointer 

e Time-out value Char(8) 
Instructions Causing Exception: 

e Dequeue 

e Signal Exception 
Lock 
A specified time period elapsed, and a Lock Object instruction was not satisfied. 
Information Passed: 

e System pointer to the object waited for 

« Time-out value Char(8) 
Instructions Causing Exception: 

e Lock Object 

e Signal Exception 
Space Location Lock Wait 


A specified time period has elapsed and a Lock Space Location instruction has not been satis- 
fied. 


Information Passed: 
e Space location Space pointer 
e Time-out value Char(8) 
Instructions Causing Exception: 
e Lock Space Location 


¢ Signal Exception 
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3C Service 
3C01 Invalid Service Session State 


The process is not in the proper service session for the request service command because of 
one of the following conditions: 


e« No service session exits for the process, and the command is other than start service 
session. 


e The process is in service session, and the command is to start service session. 
e« The process is in service session, but a previous stop service session command was issued. 
Instructions Causing Exception: 
e« Signal Exception 
3C02 Unable to Start Service Session 
The machine was unable to start a valid service session. 
Instructions Causing Exception: 


e Signal Exception 


Chapter 23. Exception Specifications 23-98 


Hex 3E, Commitment Control Exceptions 


3E Commitment Control 


SE01 


3E03 


3E04 


3E05 


Invalid Commit Block Status Change J 


An attempt was made to modify (to an invalid status) the status of a commit block attached to 
the issuing process. The exception data defines the attempted change to the commit block 
status. 


Information Passed: 
e Commit block System pointer 


e Attempted status change Char(2) 
(as defined in the modifications options in the modification template for the Modify Commit 
Block instruction) 


Instructions Causing Exception: 
¢ Modify Commit Block 
e Signal Exception 
Commit Block Is Attached to Process 


The identified commit block is attached to a process making the operation requested impossible. 
The process that has the commit block attached is identified in the exception data. 


Information Passed: 
e Commit block system pointer 
e Process control space system pointer 
Instructions Causing Exception: | 
e Destroy Commit Block J 
e Signal Exception 
Commit Blocks Control Uncommitted Changes 


The identified commit block controls uncommitted changes, and an attempt was made to detach 
the commit block from the issuing process. 


Information Passed: 

e Commit block system pointer 
Instructions Causing Exception: 

e Modify Commit Block 

¢ Signal Exception 
Operation Not Valid on Commit Block in Prepared State 


The identified Commit Block is in a prepared state. The operation attempted is therefore not 
allowed. Signalled from #COCHECK module. 


Information Passed: 

¢ Commit block System pointer 
Instructions Causing Exception: 

e Modify Commit Block 

¢« Activate Cursor 


¢ Deactivate Cursor 


« Delete Data Space Entry 
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« Destroy Commit Block 

« Destroy Cursor 

¢« Insert Data Space Entry 

e Insert Sequential Data Space Entries 
e Release Data Space Entries 

¢« Retrieve Data Space Entry 

¢ Update Data Space Entry 


3E06 Commitment Control Resource Limit Exceeded 


3E08 


3E10 


One of the resource limits for the commitment control functions has been reached. 
Information Passed: 
« Commit block System pointer 
« Condition code Char(1) 


Hex 01 = Lock limit exceeded 

Hex 02 Object list size exceeded 

Hex 03 = Limit of attached commit blocks in the system exceeded 
Hex 04 = Reposition cursor data limit exceeded 


II 


Instructions Causing Exception: 
¢ Insert Data Space Entry 
e Insert Sequential Data Space Entries 
e Modify Commit Block 
e Set Cursor 
e Signal Exception 
Object Under Commitment Control Being Journaled Incorrectly 


All objects under commitment control must have their changes journaled through the same 
journal port as the commit block. An attempt was made to place an object under commitment 
control that did not meet this condition. 


Information Passed: 


¢« Object System pointer 
e Journal port that must be used System pointer 
e Journal port currently being used System pointer 


(binary O if not currently being journaled) 
Instructions Causing Exception: 
« Modify Commit Block 
e Signal Exception 
Operation Not Valid Under Commitment Control 


An operation was attempted on an object or through an object that was currently under commit- 
ment control. The operation is not supported under commitment control. 


Information Passed: 
e Object under commitment control System pointer 
Instructions Causing Exception: 


e Copy Data Space Entries 


Chapter 23. Exception Specifications 23-100 


SET T 


3E12 


3ET3 
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¢ De-activate Cursor 
° Destroy Cursor 
« Retrieve Sequential Data Space Entries 
¢ Signal Exception 
Process Has Attached Commit Block 
An attempt was made to attach a second commit block to a process. 
Information Passed: 
e Commit block (attached) system pointer 
e Commit block (attempted to attach) System pointer 
Instructions Causing Exception: 
e Modify Commit Block 
e Signal Exception 
Objects Under Commitment Control 


An attempt was made to detach a commit block from a process that has objects under commit- 
ment control. 


Information Passed: 

e Commit block System pointer 
Instructions Causing Exception: ) 

¢ Modify Commit Block 

e Signal Exception 
Commit Block Not Journaled 


An attempt was made to attach a commit block to a process, and the commit block was not 
being journaled. 


information Passed: 

« Commit block system pointer 
Instructions Causing Exception: 

e Modify Commit Block 

e Signal Exception 
Errors During Decommit 


Errors were detected during an execution of a Decommit instruction. The exception data indi- 
cates the type of errors detected. 


Information Passed: 


« Commit block System pointer 
e Reserved (binary 0) Char(1) 
e Decommit status Char(4) 
— Damaged Bit 0 
0 = Commit block is not damaged 
1 = Commit block is damaged 
— Reserved (binary 0) Bits 1-2 
— Partially damaged Bit 3 
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Not partially damaged 
1 = Partially damaged 


— Reserved (binary 0) Bits 4-15 
— Decommit Bit 16 
0 = All changes were decommitted 


lI 


1 


— Journal read errors Bit 17 


Not all changes were decommitted 


0 = No journal read errors 
1 = Journal read errors occurred during decommit 


— Journal write errors Bit 18 


0 = No journal write errors 
1 = Journal write errors occurred during decommit 


— Partial damage to data space Bit 19 


0 = No damage encountered 
1 = Damage encountered on one or more data spaces 


— Damage to data space Bit 20 


0 No damage encountered 
1 = Damage encountered on one or more data spaces 


— Function check . Bit 21 


0 = No function check encountered 
1 = Function check encountered 


— Reserved (binary 0) Bits 22-23 
— Constant = 100 Bits 24-26 
— Reserved (binary 0) Bits 27-31 
e Reserved (binary OQ) Char(7) 
e Journal entry sequence number of start Bin(4) 


commit journal entry 
Instructions Causing Exception: 
« Decommit 
° Signal Exception 
3E15 Object Ineligible for Commitment Control 
The specified object is not eligible to be placed under commitment control. 
Information Passed: 
e Object System pointer 
¢ Reason code Char(‘1) 


Hex 01 = Object is a type that is not supported under commitment control 

Hex 02 Object is a cursor that was not activated under the issuing process 

Hex 03 = Object is already under commitment control to this another commit biock or to 
commit block 

Hex 04 = Object is a cursor that holds data space entry locks 

Hex 05 = Object is a join cursor 


Instructions Causing Exception: 
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« Modify Commit Block 
¢ Signal Exception 
3E16 Object Ineligible for Removal from Commitment Control 


The specified object cannot be removed from commitment control. 
Information Passed: 
« Object 


e Reason code 


Hex 01 = Object is a type that is not supported under commitment control 
Hex 02 = Object is not under commitment control of this commit block 


system pointer 
Char(1) 


Hex 03 = Object is a cursor holding data space entry locks 


Instructions Causing Exception: 
¢ Modify Commit Block 


e Signal Exception 
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44 Domain Violation Exceptions 
4401 Object Domain Violation 


An attempt was made to use a blocked instruction or to access a system domain object from a 
user state program. The system must be running at security level 40 to get this exception. 


The execution of the instruction is suppressed when the exception is signalled. 
information Passed: 

e Object. System pointer 
Instructions Causing Exception: 

e All blocked instructions. 


« Any instruction that contains an operand that can be a pointer or be represented in storage 
(i.e. the value for the operand is to retrieved from storage). 
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Appendix A. Instruction Summary 


This appendix provides an abbreviated format of all the instructions. The instructions are listed alpha- 
betically by instruction mnemonic. 
The summary list includes the following items for each instruction. 

e Operation Description-The name of the instruction. 

e Mnemonic-The mnemonic assigned to the instruction. 

e Operation Code-The operation code assigned to the instruction. 

e Number of Operands-The number of operands (excluding the extender) in the instruction. 

e Extender-A description of the use of the extender field. 

e Operand Syntax-The objects allowed as operands in the instruction. 


e Resulting Conditions-The conditions that can be set at the end of the standard operation in order to 
perform a conditional branch or set a conditional indicator. 


¢ Optional Forms-A notation for the optional forms that are allowed for the computational 
instructions. 


Note: This summary list can also be used as an index to identify the page where a complete 
description of each instruction can be found in this manual. The page number is the last item 
included with each instruction in this summary. : 


The following paragraphs further describe the summary list format of the last five items in the previous 
list. 


Number Of Operands 
Certain computational instructions allow a variable number of operands and are identified in the 
summary list by the following form: 

number + B 


The number defines the number of fixed operands. The B indicates the existence of variable operands 
(branch targets or indicator operands). A pair of braces around the letter indicates that the variable 
operands are optional. 


Extender Usage 


Instructions that use an extender field have a brief description of the use of the extender. Hyphens 
indicate that the extender is not used. Brackets indicate that the extender is optional. The abbrevi- 
ation BR/IND is used to mean branch or indicator options. The extender field defines the use of the 
branch or indicator operands with respect to the resulting conditions of the instruction. 


Resulting Conditions 


Resulting conditions are the status result of the operation that is used for determining a branch target, 
if any. 


The following conditions are indicated in the instruction summary. 
P,N,Z Positive, negative, zero 


Z, NZ zero, not zero 
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H, LE High. low, equal 

E, NE Equal, not equal 

PAZ Positive, zero J 
H, L, E, U High, low, equal, unequal 

Z,0,M Zero, ones, mixed 

[NJZEN]C Zero and no carry, not zero and no carry, zero and carry, not zero and carry 

S, NS Signaled, not signaled 

DE, | Exception deferred, exception ignored 

DQ, NDQ Dequeued, not dequeued 


Optional Forms 


All instructions are classified as computational or noncomputational format. The format determines 
how the operation code is interpreted and whether optional forms of the instruction are allowed. (See 
“Instruction Format” in Chapter 1. “Introduction”). 


Certain computational instructions allow optional forms. The following optional forms can be specified: 


¢ B (Branch Form)-The resulting conditions of the operation are compared with the branch options 
specified in the extender field. If one of the options is satisfied, a branch is executed to the branch 
target corresponding to the branch option. 


e | (Indicator Form)-The resulting conditions of the operation are compared with the indicator options 
specified in the extender field. If one of the options is satisfied, the indicator corresponding to that 
option is assigned a value of hex F1. The other indicators referred to by the operation are -) 
assigned a value of hex FO. 


¢ S (Short Form)-The operand that acts as a receiver in the instruction can also be one of the source 
operands. 


e R (Round Form)-lf the result of the operation is to be truncated before being placed in the receiver, 
rounding is performed. 
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Instruction Stream Syntax 


In this instruction summary, the following metalanguage is used to describe the machine interface 
instruction set operand syntax. 

Metasymbol Meaning 

{} Choose from a series of alternatives 

[ ] Enclose an optional entry or entries 


| OR - used to separate alternatives 


N. Repeat previous entry, up to N times 

= ls defined as - define a metavariable Metavariable ::= Metadefinition 
DESC-{} Description of a metavariable in English 

Notes: 


1. Some of the computational op codes require an extender field while on other op codes an extender 
field is optional. Some computational op codes may be optionally short, or round. 
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Program Object Definitions 
ARG-LIST ::= DESC-{operand list which defines an argument list} 


B-ARRAY ::= DESC-{array of binary variables} B-PT ::= DESC-{branch 
point} BIN ::= DESC-{binary} BIN[N] ::= DESC-{binary object 
with precision N} BT ::= DESC-{instruction number | relative instruction 
number | instruction pointer | branch pointer | IDL 
element | null} 


C-ARRAY ::= DESC-{array of character string variables} CHAR ::= 
DESC-{character string which is either variable or constant} 
CHAR[N] ::= DESC-{string at least N bytes long} CHARV ::= 
DESC-{char variable} CHARC ::= DESC-{char constant} 


D-PTR ::= DESC-{data pointer} 
EXCP-DESC ::= DESC-{exception description} 


F-BT ::= DESC-{instruction number | relative instruction number | 
branch point} F-P ::= DESC-{floating-point value} 


IDL ::= DESC-{instruction definition list} IT ::= DESC-{char|numeric 
variable used as an indicator target} I-ENT PT ::= DESC-{internal entry 
point} I-PTR ::= DESC-{instruction pointer} 


NULL ::= DESC-{indicates a null operand [X’0000’]} NUMERIC 
::= DESC-{binary | zoned | packed | numeric scalar} N-ARRAY ::= 
DESC-{array of numeric variable} 


OP-LIST ::= DESC-{operand list} 


PROCESS ::= DESC-{character string that names a process} PTR ::= 
DESC-{a 16-byte, 16-byte-boundary-aligned pointer element} P-ARRAY ::= 
DESC-{an array of 16 bytes, 

16-byte-boundary-aligned pointer(s)} 


SPDO ::= DESC-{space pointer data object} S-PTR ::= DESC-{system 
pointer} SPP ::= DESC-{space pointer} SPP-ARRAY ::= DESC-{an array of 
space pointer variables} 


Notes: 


Instruction Summary 


1. NUMERIC, CHAR, BIN, and UBIN may be followed by the special characters S, C, V. CHAR, BIN, 
and UBIN may also be followed by the special character |. These characters further qualify the 


object as being scalar, constant, variable or immediate, respectively. 


2. All array objects are variable. 
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ACTV ENTRY ::= DESC-{SPP that addresses an activation} 

AG ::= DESC-{S-PTR that addresses an access group} 

AL ::= DESC-{S-PTR that addresses an authorization list} 

CD ::= DESC-{S-PTR that addresses a controller description} 
CSD ::= DESC-{S-PTR that addresses a class of service description} 
CONTEXT ::= DESC-{S-PTR that addresses a context} 

CURSOR ::= DESC-{S-PTR that addresses a cursor} 

DATA SPACE ::= DESC-{S-PTR that addresses a data space} 
DCT ::= DESC-{S-PTR that addresses a dictionary} 

DS-INDEX ::= {S-PTR that addresses a data space index} 
INDEX ::= DESC-{S-PTR that addresses an index} 

LUD ::= DESC-{S-PTR that addresses a logical unit description} 
MD ::= DESC-{S-PTR that addresses a mode description} 
MODULE ::= DESC-{S-PTR that addresses a module} 

ND ::= DESC-{S-PTR that addresses a network description} 
PCS ::= DESC-{S-PTR to process control space} 

PROGRAM ::= DESC-{S-PTR that addresses a program} 
SPACE ::= DESC-{a system pointer pointing to a space object} 
QUEUE ::= DESC-{S-PTR that addresses a queue} 

QUEUE SPACE ::= DESC-{S-PTR that addresses a queue space} 


USER PROFILE ::= DESC-{S-PTR that addresses a user profile} 


Instruction Summary 
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ZC ::= DESC-{zero with carry} 


[N]ZC ::= DESC-{[not] zero with carry} 
Z[N]C ::= DESC-{zero with [no] carry} 
[N]Z[N]C ::= DESC-{[not] zero with [no] carry} 
CR ::= DESC-{completed record} 

DE ::= DESC-{deferred} 

DEN ::= DESC-{denormalized} 

[N]DQ ::= DESC-{[Not ]dequeued} 

ECE ::= DESC-{escape code encountered} 
E ::= DESC-{equal} 

[N]F ::= DESC-{[Not]found} 

H ::= DESC-{high} 

| ::= DESC-{ignored} 

IN :: = DESC-{infinity} 

L ::= DESC-{low} 

M ::= DESC-{mixed} 

N ::= DESC-{negative} 

NaN ::= DESC-{symbolic not-a-number} 
NCO ::= DESC-{null compare operand} 
NE ::= DESC-{not equal} 

NRN ::= DESC-{normalized real number} 


NS ::= DESC-{not signaled} 


NZ ::= DESC-{not zero} 

O ::= DESC-{ones} 

P ::= DESC-{positive} 

RO ::= DESC-{receiver overrun} 


S ::= DESC-{signaled} 


SE ::= DESC-{source exhausted} 
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TR ::= DESC-{truncated record} 


C U ::= DESC-{unequal} 
UN ::= DESC-{unordered} 


Z ::= DESC-{zero} 
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Operation 
Description 


Activate 
Program 


Add Logical 
Character 


Add Numeric 


Add Space 
Pointer 


Allocate Heap 
Space Storage 


And 


Branch 


Compute Array 
Index 


Call Internal 


Call External 


Concatenate 


Compute Date 
Duration 


Clear Bit in 
String 


Clear Invocation 


Exit 


Compute Math 
Function Using 


One Input Value 


Compute Math 
Function Using 
Two Input 
Values 


Compare Bytes 
Left-Adjusted 


Mnemonic 


ACTPG 


ADDLC 


ADDN 


ADDSPP 


ALCHSS 


AND 


CALLX 


CAT 


CDD 


CLRBTS 


CLRIEXIT 


CMF1 


CMF2 


CMPBLA 


Op 
Code 


0212 


1023 


1043 


0083 


03B3 


1093 


1011 
1044 


0293 


0283 


10F3 


0424 


102E 


0250 


100B 


100C 


10C2 


Number 
of 
Operands 


3+[B] 


4+(B] 


2+B 


Operand 
Syntax 


{ACTV 
ENTRY | 


Resulting 
Condi- 
tions 


PROGRAM},PROGRAM 


CHARV, 
CHARS.2., 
[BT.4. | IT.4.] 


NUMERICV, 
NUMERICS.2., 
[BT.4. | IT.4.] 


SPP.2., BINS 


SPP, {BIN | 
NULL}, BIN 


CHARV, 
CHARS.2., 
[BT.3. | IT.3.] 


BT 
BINV, BINS.3. 


I-ENT PT, 
{ARG LIST | 
NULL}, I-PTR 


PROGRAM | 
SPP, {ARG 

LIST | NULL}, 
{IDL | NULL} 


CHARV, 
CHARS.2. 


NUMERICV, 
CHAR, 
CHAR, SPP 


{CHARV | 
NUMERICV}, 
BINS 


NUMERICV, 
CHARS[2], 
NUMERICS, 
(BT.4. | IT.4.] 


NUMERICV, 
CHARS[2], 
NUMERICS, 
NUMERICS, 
[BT.4. | IT.4.] 


{CHARS | 
NUMERICS}.2., 
{BT.3. | IT.3.} 


[N]Z[NIC 


P,N, 2, 
UN 


Z, NZ 


H, L, E 


Optional 
Forms 
[B | 1, S$] 
[B | 1, §, 
R] 

[B | |, S$] 
[B | 1] 
(B | I] 
{B | |} 


Instruction Summary 


2-3 


2-15 


9-11 


2-32 


2-41 


2-17 


Appendix A. Instruction Summary 


Operation 
Description 


Compare Bytes 
Left-Adjusted 
With Pad 


Compare Bytes 
Right-Adjusted 


Compare Bytes 
Right-Adjusted 
With Pad 


Compare 
Numeric Value 


Compare 
Pointer for 
Space Address- 
ability 


Compare 
Pointer for 
Object Address- 
ability 

Compare 
Pointers for 
Equality 


Compare 
Pointer Type 


Compare Space 
Addressability 


Compress Data 


Copy Bytes to 
Bits Arithmetic 


Copy Bytes to 
Bits Logical 


Mnemonic 


CMPBLAP 


CMPBRA 


CMPBRAP 


CMPNV 


CMPPSPAD 


CMPPTRA 


CMPPTRE 


CMPPTRT 


CMPSPAD 


CPRDATA 


CPYBBTA 


CPYBBTL 


Op 
Code 


10C3 


10C6 


10C7 


1046 


10E6 


10D2 


1012 


10E2 


10F2 


1041 


104C 


103C 


Number 
of 
Operands 
3+B 


2+B 


3+B 


2+8B 


2+8B 


2+B 


3+[B] 


2+8B 


2+8B 


Operand 
Syntax 


{CHARS | 
NUMERICS}.3., 
{BT.3. | !T.3.} 


{CHARS | 
NUMERICS}.2., 
{BT.3. | IT.3.} 


{CHARS | 
NUMERICS}.3., 
{BT.3. | IT.3.} 


NUMERICS.2., 
{BT.4. | IT.4.} 


{SPP | 
D-PTR}, 
{NUMERICV | 
CHARV | C- 
N-ARRAY | 
SPP | 

D-PTR}, 
{BT.4. | IT.4.} 


{D-PTR | SPP 
| S-PTR | 
|-PTR}.2., 
{BT.2. | IT.2.} 


{ Any PTR 
}.2. 


{D-PTR | SPP 
| S-PTR | 
|-PTR}, 


Resulting 
Condi- 
tions 

H, LE 


H,LE 


H&E 


H, L, E, 
UN 


H,L.E, Uv 


E, NE 


E, NE 


E, NE 


{(CHARS[1]NULL}, 


{BT.2. | IT.2.} 


{CHARV | 
C-ARRAY | 
NUMERICV | 
N-ARRAY | 
PTR | 
P-ARRAY.2.}, 
{BT.4. | IT.4.} 


Space 
Pointer 


{NUMERICV | 
CHARV}, 
BINI.2., 
{NUMERICV | 
CHARV} 


{NUMERICV | 
CHARV}, 
BINI.2., 
{NUMERICV | 
CHARV} 


H,L,—, U 


Instruction Summary 


Optional 
Forms 


{B | |} 


{B | |} 


{B | |} 


{B | I} 


{B | |} 


[B | 1] 


[B | !] 


{B | |} 


{B | I} 


Page 


2-19 


2-21 


2-23 


2-25 


4-5 


4-3 


4-7 


4-9 


2-28 


2-124 


2-126 


Appendix A. Instruction Summary A-9 


Operation 
Description 


Copy Bytes 
Left-Adjusted 


Copy Bytes 
Left-Adjusted 
With Pad 


Copy Bytes 
Overlap Left- 
Adjusted 


Copy Bytes 
Overlap Left- 
Adjusted With 
Pad 


Copy Bytes 


Right-Adjusted 


Copy Bytes 


Right-Adjusted 


With Pad 


Copy Bytes 
Repeatedly 


Copy Bits Arith- 


metic 


Copy Bits 
Logical 


Copy Bits With 


Left Logical 
Shift 


Copy Bits With 
Right Arithmetic 


Shift 


Copy Bits With 


Right Logical 
Shift 


Copy Bytes With 


Pointers 


Mnemonic 


CPYBLA 


CPYBLAP 


CPYBOLA 


CPYBOLAP 


CPYBRA 


CPYBRAP 


CPYBREP 


CPYBTA 


CPYBTL 


CPYBTLLS 


CPYBTRAS 


CPYBTRLS 


CPYBWP 


Op 
Code 


10B2 


10B3 


10BA 


10BB 


10B6 


10B7 


10BE 


102C 


101C 


102F 


101B 


103F 


0132 


Number 
of 
Operands 
2 


Operand 
Syntax 


(NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS}.2. 


{NUMERICV | 
CHARV}.2. 


{NUMERICV | 
CHARV}.2., 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS}.2. 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}.2., 
BINI.2. 


{NUMERICV | 
CHARV}.2., 
BINI.2. 


{CHARV | 
NUMERICV}, 
{CHARS | 
NUMERICS}, 
CHARS[2] 


{CHARV | 
NUMERICV}, 
{CHARS | 
NUMERICS}, 
CHARS[2] 


{CHARV | 
NUMERICV}, 
{CHARS | 
NUMERICS}, 
CHARS[2] 


{CHARV | 
PTR}, 
{CHARV | 
PTR | NULL} 


Instruction Summary 


Optional 
Forms Page 


Resulting 
Condi- 
tions 


2-110 


2-112 


2-114 


2-116 


2-120 


2-122 


2-118 


2-100 


2-102 


2-104 


2-106 


2-108 


“ - 4-12 


A-10 


Appendix A. Instruction Summary 


Operation 
Description 


Copy Extended 
Characters Left- 
Adjusted With 
Pad 


Copy Hex Digit 
Numeric to 
Numeric 


Copy Hex Digit 
Numeric to 
zone 


Copy Hex Digit 
zone to 
Numeric 


Copy Hex Digit 
Zone to Zone 


Copy Numeric 
Value 


Create Heap 
Space 


Compute Time 
Duration 


Compute 
Timestamp 
Duration 


Convert BSC to 
Character 


Convert Char- 
acter to BSC 


Convert Char- 
acter to Hex 


Convert Char- 
acter to MRJE 


Convert Char- 
acter to 
Numeric 


Convert Char- 
acter to SNA 


Mnemonic 


CPYECLAP 


CPYHEXNN 


CPYHEXNZ 


CPYHEXZN 


CPYHEXZZ 


CPYNV 


CRTHS 


CTD 


CTSD 


CVTBC 


CVTCB 


CVTCH 


CVTCM 


CVTCN 


CVTCS 


Op 
Code 


1053 


1092 


1096 


109A 


109E 


1042 


03B2 


0454 


043C 


10AF 


108F 


1082 


108B 


1083 


10CB 


Number 
of 


Operands 


3 


2+([B] 


3+ [B] 


3+ [B] 


3 + [B] 


3+ [B] 


Operand 
Syntax 


D-PTR 
CHARS,D-PTR 
CHARS,CHAR 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


{NUMERICV | 
CHARV}, 
{NUMERICS | 
CHARS} 


NUMERICV, 
NUMERICS, 
(BT.4. | IT.4.] 


BINV, SPP 


NUMERICV, 
CHAR, 
CHAR, SPP 


NUMERICV, 
CHAR, 
CHAR, SPP 


CHARV, 
CHARV[3], 
CHARS, 
{BT.3. | IT.3.} 


CHARV, 
CHARV[3], 
CHARS, 
{BT.2. | IT.2.} 


CHARV, 
CHARS 


CHARV, 
CHARV[13], 
CHARS, 
{BT.2. | IT.2.} 


NUMERICV, 
CHARS, 
CHARS[7] 


CHARV, 
CHARV[15], 
CHARS, 

{BT.2. | IT.2.} 


Resulting 


Condi- 
tions 


P,N, 2, 


SE, RO 


SE, RO 


Appendix A. Instruction Summary A-11 


Optional 
Forms 


(B|!,R] 


[B | I] 


[B | 1] 


[B | !] 


Instruction Summary 


Page 


2-128 


2-132 


2-134 


2-136 


2-138 


7-6 


3-16 


2-48 


2-52 


2-55 


2-57 


2-62 


2-65 


Operation 
Description 


Convert 
Decimal Form 
to Floating-Point 


Convert 
External Form 
to Numeric 
Value 


Convert 
Floating-Point to 
Decimal Form 


Convert Hex to 
Character 


Convert MRJE 
to Character 


Convert 
Numeric to 
Character 


Convert SNA to 
Character 


Convert Date 


Convert Time 


Convert 
Timestamp 


Decompress 
Data 


De-activate 
Program 


Decrement Date 


Decrement time 


Decrement 
timestamp 


Dequeue 


Destroy Heap 
Space 


Mnemonic 


CVTDFFP 


CVTEFN 


CVTFPDF 
CVTHC 
CVTMC 
CVTNC 
CVTSC 
CVTD 
CVTT 
CVTTS 
DCPDATA 


DEACTPG 


DECD 


DECT 


DECTS 


DEQ 


DESHS 


Op 


Code 


107F 


1087 


10BF 


1086 


10AB 


10A3 


10DB 


040F 


O041F 


043F 


1051 


0225 


0414 


0444 


040C 


1033 


03B1 


Number 
of 
Operands 
3 


3 + [B] 


3+ [B] 


3+(B] 


Operand 
Syntax 


F-PS, 
NUMERICS, 
NUMERICS 


NUMERICV, 
CHARS, 
{CHARS[3] | 
NULL} 


NUMERICV, 
NUMERICV, 
F-PS 


CHARV, 
CHARS 


CHARV, 
CHARV[6], 
CHARS, 
{BT.2. | IT.2.} 


CHARV, 
NUMERICS, 
CHARS[7] 


CHARV, 
CHARV[14], 
CHARS, 

{BT.3. | IT.3.} 


CHAR, 
CHAR, SPP 


CHAR, 
CHAR, SPP 


CHAR, 
CHAR, SPP 


SPP 


PROGRAM | 
NULL 


CHAR, 
CHAR, 
NUMERICV, 
SPP 


CHAR, 
CHAR, 
NUMERICV, 
SPP 


CHAR, 
CHAR, 
NUMERICV, 
SPP 


CHARYV, SPP, 
QUEUE, 
[BT.2. | IT.2.] 


BINV 


Resulting 
Condi- 
tions 


SE, RO 


DO, NDQ 


Optional 
Forms 


Round 


[B | !] 


[B | !] 


[B | 1] 


Instruction Summary 


Page 


2-74 


2-76 


2-79 


2-82 


2-84 


2-88 


2-90 


3-22 


3-25 


3-28 


2-143 


9-12 


3-31 


3-35 


3-38 


12-3 


Appendix A. Instruction Summary 


Operation 
Description 


Divide 


Divide With 
Remainders 


Extended Char- 
acter Scan 


Edit 


End 


Enqueue 


Ensure Object 


Exchange Bytes 


Extract Expo- 
nent 


Extract Magni- 
tude 


Find Inde- 
pendent Index 
Entry 


Find Relative 
Invocation 
Number 


Free Heap 
Space Storage 


Free Heap 
Space Storage 
from Mark 


Insert Inde- 
pendent Index 
Entry 


Lock Object 


Lock Space 
Location 


Materialize 
Access Group 
Attributes 


Materialize Acti- 
vation Group 
Attributes 


Materialize 
Authority List 


Mnemonic 


DIV 


DIVREM 


ECSCAN 


EDIT 


END 
ENQ 


ENSOBJ 
EXCHBY 


EXTREXP 


EXTRMAG 


FNDINXEN 


FNDRINVN 


FREHSS 


FREHSSMK 


INSINXEN 


LOCK 
LOCKSL 


MATAGAT 


MATAGPAT 


MATAL 


Op 
Code 


104F 


1074 


10D4 


10E3 


0260 
036B 


0381 
10CE 


1072 


1052 


0494 


0543 


03B5 


03B9 


04A3 


O3F5 
03F6 


03A2 


02D3 


01B3 


Number 
of 
Operands 
3+(B] 


4+([B] 


4+[B] 


Operand 
Syntax 


NUMERICV, 
NUMERICS.2., 
[BT.4. | IT.4.] 


NUMERICV, 
NUMERICS.2., 
NUMERICV 


B-ARRAY, 
CHARS, 
CHARS, 
CHARS[1], 
{BT.3. | |T.3.} 


CHARV, 
NUMERICS, 
CHARS 


QUEUE, 
CHARS, SPP 


S-PTR 
{CHARV | 


NUMERICV}.2. 


BINV, F-PS, 
{BT.4. | IT.4.} 


NUMERICV, 
NUMERICS, 
(BT.3. | IT.3.] 


SPP, INDEX, 
SPP.2. 


BIN, 
{CHARS[48] 
| NULL}, SPP 


SPP 


SPP 


INDEX, SPP.2. 


SPP 


SPP, 
CHARS[1] 


SPP, AG 


SPP, UBIN, 
CHARS[1] 


SPP, AL, SPP 


Instruction Summary 


Resulting Optional 
Condi- Forms Page 
tions 
P,N, Z, [B | 1, S, 2-146 
UN R} 
P/N, Z [B|1,S 2-150 
R] 
P, Z, ECE [B | |] 2-167 
- - 2-154 
- - 9-14 
- - 12-9 
- - 19-3 
- - 2-162 
NRN, [B | I] 2-171 
DEN, IN, 
NaN 
P, Z, UN [B | 1, S] 2-174 
- - 11-12 
- - 21-3 
: z= 7-13 
‘ : 7-15 
i - 11-16 
- 13-3 
- 13-8 
“ 7 19-5 
- - 9-19 
e - 17-7 


A-13 


Appendix A. Instruction Summary 


Operation 
Description 


Materialize Allo- 
cated Object 
Locks 


Materialize 
Authority 


Materialize 
Authorized 
Objects 


Materialize 
Authorized 
Users 


Materialize 
Bound Program 


Materialize 
Context 


Materialize 
Dump Space 


Materialize 
Data Space 
Record Locks 


Materialize 
Exception 
Description 


Materialize 
Instruction Attri- 
butes 


Materialize 
Invocation 


Materialize 
Invocation Attri- 
butes 


Materialize 
Invocation Entry 


Materialize 
Invocation 
Stack 


Materialize 
Machine Attri- 
butes 


Materialize 
Machine Data 


Materialize 
Program 


Mnemonic 


~ MATAOL 


MATAU 


MATAUOBJ 


MATAUU 


MATBPGM 


MATCTX 


MATDMPS 


MATDRECL 


MATEXCPO 


MATINAT 


MATINV 


MATINVAT 


MATINVE 


MATINVS 


MATMATR 


MATMDATA 


MATPG 


Op 
Code 


O3FA 


0153 


013B 


0143 


02C6 


0133 


04DA 


032E 


03D7 


0526 


0516 


0533 


0547 


0546 


0636 


0522 


0232 


Number 
of 
Operands 
2 


Operand 
Syntax 


SPP, {S-PTR | 
SPDO} 


SPP, S-PTR, 
{USER 
PROFILE | 
NULL} 


SPP, USER 
PROFILE, 
CHARS[1] 


SPP, S-PTR, 
CHARS[1] 


SPP, S-PTR 


SPP, 
{CONTEXT | 
NULL}, 
CHARS 


SPP, S-PTR 


SPP, SPP 


SPP, 
EXCP-DESC, 
CHARS[1] 


SPP, CHARS 


SPP.2. 


SPP, 
{CHARS[48] 
| NULL}, SPP 


CHARV, 
{CHARV.1. | 
NULL}, 
CHARS.1. | 
NULL} 


SPP, {S-PTR | 
NULL} 


SPP, 
CHARS[2] | 
SPP 


CHAR, 
{CHAR [2] | 
NUMERICV } 


SPP, 
PROGRAM 


Instruction Summary 


Optional 
Forms 


Resulting 
Condi- 
tions 


Page 


J 


-- Heading 
“MATAOL’ 
unknown 


2 - 17-3 


17-12 


17-20 


e - 14-3 
- - 21-8 


21-14 


21-18 


21-28 


21-32 
22-4 


22-30 


8-24 


A-14 


Appendix A. Instruction Summary 


Instruction Summary 


Operation Op Number Operand Resulting Optional 

Description Mnemonic Code of Syntax Condi- Forms Page 
Operands tions 

Materialize MATPRAGP 0331 1 SPP - - 18-3 


Process Acti- 
vation Groups 


Materialize MATPRATR 0333 3 SPP, {PCS | - - 18-5 
Process Attri- NULL}, 
butes CHARS(1 ] 
Materialize MATPRECL O31E 2 SPP, SPP - - 13-20 
Process Record 
Locks 
Materialize MATPRLK 0312 2 SPP, {PCS | - - 13-17 
Process Locks NULL} 
Materialize MATPRMSG 039C 4 SPP, SPP, - - 15-3 
Process {SPP | 
Message NULL}, SPP 
Materialize MATPTR 0512 2 SPP, {S-PTR | - - 21-37 
Pointer D-PTR | SPP | 
|-PTR} 
Materialize MATPTRL 0513 3 SPP.2., BINS - - 21-46 
Pointer 
Locations 
Materialize MATQAT 0336 2 SPP, QUEUE - - 12-12 
Queue Attri- : 
butes 
Materialize MATQMSG 033B 3 SPP, S-PTR, - - 12-16 
Queue Mes- CHARS[16] 
sages 
Materialize MATRMD 0352 2 SPP, - - 19-9 
Resource Man- CHARS[8] 
agement Data 
Materialize MATS 0036 2 SPP, S-PTR - - 6-11 
Space Attri- 
butes 
Materialize MATSELLK 033E 2 SPP, {S-PTR | - - 13-24 
Selected Locks SPP} 
Materialize MATSOBJ O53E 2 SPP, S-PTR - - 21-48 
System Object 
Materialize MATUP 013E 2 SPP, USER - - 17-25 
User Profile PROFILE 
Modify Auto- MODASA O2F2 2 {SPP | - - 9-23 
matic Storage NULL}, BINS 
Allocation 
Modify Excep- MODEXCPD O3EF 3 EXCP-DESC, - - 14-6 
tion Description SPP, 
CHARS[4] 
Modify Inde- MODINX 0452 2 S-PTR, - - 11-23 
pendent Index CHARS[4] 
Modify Space MODS 0062 2 S-PTR, BINS - - 6-15 
Attributes 
Multiply MULT 104B 3+([B] NUMERICV, P,N, Z, [B |1,§S, 2-177 
NUMERICS.2., UN R] 
[BT.4. | IT.4.] 


Appendix A. Instruction Summary A-15 


Instruction Summary 


Operation Op Number Operand Resulting Optional 
Description Mnemonic Code of Syntax Condi- Forms Page 
Operands tions 
Negate NEG 1056 2+([B] NUMERICV, PN, Z, [B | 1, $] 2-181 
NUMERICS, UN 
[BT.4. | IT.4.] 
No Operation NOOP 0000 0 - - - 10-3 
No Operation NOOPS 0001 1 UBINI - - 10-4 
and Skip 
Not NOT 108A 2+[B] CHARV, Z, NZ [B/1, S$] 2-184 
CHARS, 
[BT.2. | IT.2.] 
Or OR 1097 3+([B] CHARV, Z, NZ [B | 1, S] 2-187 
CHARS.2., 
[BT.2. | IT.2.] 
Override OVRPGATR 0006 2 UBINI.2. - - 10-5 
Program Attri- 
butes 
Remainder REM 1073. 3+([B] NUMERICV, P/N, Z [B | 1, S] 2-190 
NUMERICS.2.,, 
[BT.3. | IT.3.] 
Retrieve Excep- RETEXCPD O3E2 2 SPP, - - 14-9 
tion Data CHARS[1 ] 
Remove Inde- RMVINXEN 0484 4 {SPP | - te 11-26 
pendent Index NULL}, 
Entry INDEX, SPP.2. 
Resolve Data RSLVDP 0163 3 D-PTR, - - 4-14 i 
Pointer {CHARS[32] J 
| NULL}, 
{S-PTR | 
NULL} 
Resolve System RSLVSP 0164 4 S-PTR, - - 4-17 
Pointer {CHARS[34] 
| NULL}, 
{S-PTR | 
NULL}, 
{CHARS[2“ | 
NULL} 
Return From RTNEXCP 03E1 1 SPP - - 14-12 
Exception 
Return External RTX O2A1 1° {BINS | - - 9-25 
NULL} 
Scale SCALE 1063. 3+([B] NUMERICV, P,N, Z, [B | 1, S] 2-194 
NUMERICS, UN 
BINS, [BT.4. | 
IT.4.] 
Scan SCAN 1003. 3+([B] {BINV | P, Z, NCO [B} I] 2-198 
B-ARRAY}, 
CHARS.2., 
[BT.3. | IT.3.] 
Scan With SCANWC 10E4 4+([B] SPP, H, LE, [B, 1 2-201 
Control CHARV[8], NF 
CHARS[4], ’ 
[BT.4. | IT.4.] So" 


Appendix A. Instruction Summary A-16 


Operation 
Description 


Search 


Set Access 
State 


Set Argument 
List Length 


Set Bit in String 


Set Data Pointer 


Set Data Pointer 
Addressability 


Set Data Pointer 
Attributes 


Set Heap Space 
Storage Mark 


Set Invocation 
Exit 


Set Instruction 
Pointer 


Set System 
Pointer From 
Pointer 


Set Space 
Pointer 


Set Space 
Pointer with Dis- 
placement 


Set Space 
Pointer From 
Pointer 


Mnemonic 


SEARCH 


SETACST 
SETALLEN 


SETBTS 


SETDP 


SETDPADR 


SETDPAT 
SETHSSMK 
SETIEXIT 
SETIP 


SETSPFP 


SETSPP 


SETSPPD 


SETSPPFP 


Op 
Code 


1084 


0341 


0242 


101E 


0096 


0046 


004A 


03B6 


0252 


1022 


0032 


0082 


0093 


0022 


Number 
of 
Operands 
4+([B] 


Operand 
Syntax 


{BINV | 
B-ARRAY}, 
{N-ARRAY | 
C-ARRAY}, 
{CHARV | 
NUMERICV}, 
BINS, {BT.2. | 
IT.2.} 


SPP 


ARG-LIST, 
BINS 


{CHARV | 
NUMERICV}, 
BINS 


D-PTR 
{NUMERICV | 
N-ARRAY | 
CHARV | 
C-ARRAY} 


D-PTR 
{NUMERICV | 
N-ARRAY | 
CHARV | 
C-ARRAY} 


D-PTR, 
CHARS[7] 


SPP, BIN 


S-PTR, ARG 
LIST NULL 


|-PTR, F-BT 


S-PTR, 
{D-PTR | SPP 
| S-PTR | 
|-PTR} 


SPP, {CHARV 
| C-ARRAY | 
NUMERICV | 
N-ARRAY | 
PTR | 
P-ARRAY} 


SPP, {CHARV 
| C-ARRAY | 
NUMERICV | 
N-ARRAY | 
PTR | 
P-ARRAY} 


SPP, {S-PTR | 
D-PTR | SPP} 


Resulting 
Condi- 
tions 

PZ 


Appendix A. Instruction Summary A-17 


Instruction Summary 


Optional 
Forms 


[B | !J 


Page 


2-209 


19-31 


9-27 


2-212 


5-7 


5-9 


5-11 


7-25 


9-29 


2-214 


4-24 


5-14 


5-16 


4-22 


Operation 
Description 


Set Space 
Pointer Offset 


Signal Exception 


Sense Exception 
Description 


Store and Set 
Computational 
Attributes 


Store Param- 
eter List Length 


Store Space 
Pointer Offset 


Subtract Logical 
Character 


Subtract 
Numeric 


Subtract Space 
Pointer Offset 


Subtrace Space 
Pointer For 
Offset 


Test Authority 


Test Extended 
Authorities 


Test Exception 


Trim Length 


Test Bit in 
String 


Test Bits Under 
Mask 


Test and 
Replace Char- 
acters 


Mnemonic 


SETSPPO 
SIGEXCP 
SNSEXCPD 


SSCA 


STPLLEN 
STSPPO 


SUBLC 
SUBN 


SUBSPP 


SUBSPPFO 


TESTAU 


TESTEAU 


TESTEXCP 
TRIML 


TSTBTS 


TSTBUM 


TSTRPLC 


Op 


Code 


0092 


10CA 


03E3 


107B 


0241 


00A2 


1027 


1047 


0087 


0033 


10F7 


10FB 


104A 


10A7 


100E 


102A 


10A2 


Number 
of 
Operands 
2 


2+(B] 


2+(B] 


2+B 


2+B 


Operand 
Syntax 


SPP, BINS 


SPP.2., [BT.2. 
| '7.2.] 


SPP.3. 


CHARV[S5], 
{CHARS[5] | 
NULL}, 
{CHARS[5] | 
NULL} 


BINV 
BINV, SPP 


CHARV, 
CHARS.2., 
(BT.4. | IT.4.] 


NUMERICV, 
NUMERICS.2., 
[BT.4. | IT.4.] 


SPP.2., BINS 


BINS, SPP.2. 


{CHARV[2] | 
NULL}, 
{S-PTR | 
SPDO}, 
CHARS[2] 


{CHARV[8] | 
NULL}, 
CHARS[8], 
{BINS[2] | 
NULL} 


SPP, 
EXCP-DESC, 
[BT.2. | IT.2.] 


NUMERICV, 
CHARS, 
CHARS[1] 


{CHARS | 
NUMERICS}, 
BINS, {BT.2. | 
IT.2.} 


{CHARS | 


NUMERICS}.2., 


{BT.3. | IT.3.} 


CHARV, 
CHARS 


Instruction Summary 


Resulting Optional 

Condi- Forms Page 
tions 

7 - 5-18 

|, DE [B | 1] 14-19 
- - 14-15 
- - 2-216 
: - 9-31 

bs - 5-20 

Z, NZ, C, [B | 1, S] 2-220 
NC 

P,N, Z, [B | 1, §S, 2-223 
UN R] 

z - 5-22 

- - 5-24 

- - 17-29 
- - 17-34 
S, NS [B | 1] 14-24 
- - 2-240 
Z,O {B | |} 2-229 
Z,O, M {B | |} 2-231 
3 - 2-227 
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Operation 
Description 
Unlock Object 


Unlock Space 
Location 


Verify 


Wait On Time 


Transfer Control 


Transfer Object 


Lock 


Translate 


Translate With 


Table 


Exciusive Or 


Mnemonic 


UNLOCK 
UNLOCKSL 


VERIFY 


WAITTIME 
XCTL 


XFRLOCK 


XLATE 


XLATEWT 


XOR 


Op 
Code 


O3F 1 
03F2 


10D7 


0349 
0282 


0382 


1094 


109F 


1098 


Number 
of 
Operands 


3+[B] 


3+([B] 


Operand 
Syntax 


SPP 


SPP, 
CHARS[1] 


{BINV | 
B-ARRAY}, 
CHARS.2. 
[BT.2. | IT.2.] 


CHARS. 16. 


PROGRAM | 
SPP, {ARG 
LIST | NULL} 


PCS, SPP 


CHARV, 
CHARS, 
{CHARS | 
NULL}, 
CHARS 


CHARV, 
CHARS, 
CHARS 


CHARV, 
CHARS.2., 
(BT.2. | IT.2.] 


Resulting 
Condi- 
tions 


P,Z 


Z, NZ 


Instruction Summary 


Optional 
Forms 


(B | !] 


(B | 1, S] 


Page 


13-30 
13-33 


2-242 


18-18 
9-33 


13-27 


2-233 


2-235 


2-164 
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index 


A 


absolute instruction number 1-1 
activation entry 9-3 
activation group 9-3, 9-7, 9-20, 9-21, 9-35, 18-3 
activation count 9-21 
heap space count 9-21 
mark 9-21 
name 9-21 
root program 9-21 
storage address recycling key 9-21 
activation group heap list 9-20 
activation group mark 18-3 
activation mark 9-3 
actvation entry 9-7, 9-35 
array 1-4 
authorization management instructions 17-1 
authorization required 1-3 
automatic storage frame (ASF) 9-7, 9-35 


byte string 1-1 


C 


Character 1-3 
compound operands 1-1 
explicit base 1-2 
subscript 1-1 
substring 1-2 
computation and branching instructions 2-1 
context management instructions 16-1 


D 


data pointer 1-4 
data pointer defined scalar 1-4 
dump space management instructions 20-1 


Exceptions 1-3, 14-1 
management instructions 14-1 
specifications 23-1 

external entry point 9-7, 9-35 


H 


heap management instructions 7-1 


immediate operands 1-1 
IMPL (initial microprogram load) 22-5 
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IMPLA (initial microprogram load abbreviated) 22-5 
independent index instructions 11-1 
initial microprogram load (IMPL) 22-5 
initial microprogram load abbreviated (IMPLA) 22-5 
instruction definition list element 1-4 
instruction format 

authorization required 1-3 

Exceptions 1-3 

limitations 1-3 

lock enforcement 1-3 

resultant conditions 1-3 
instruction forms 

number 1-4 

pointer 1-4 
instruction summary A-1 
invocation count 9-7, 9-13, 9-35 
invocation exit and deactivation 9-13 
invocation mark 9-7, 9-35 
invocation number 9-7, 9-35 
invocation type 9-7, 9-35 
IPL (initial program load) 22-11 


L | 

LEAR (lock exclusive allow read) 13-4 
LENR (lock exclusive no read) 13-4 
limitations 1-3 

lock enforcement 1-3 » 
lock exclusive allow read (LEAR) 13-4 
lock exclusive no read (LENR) 13-4 
lock management instructions 13-1 
lock shared read (LSRD) 13-4 

lock shared read only (LSRO) 13-4 
LSRD (lock shared read) 13-4 

LSRO (lock shared read only) 13-4 
LSUP (lock shared update) 13-4 


M 

machine initialization status record (MISR) 22-5, 
22-11 

machine interface support functions instructions 22-1 

machine observation instructions 21-1 

mark count 9-7, 9-35 

Materialize Invocation Attributes 9-7, 9-35 

MISR (machine initialization status record) 22-5, 
22-11 


null operands 1-1 


X-1 


C. 


O 


object 
object mapping table 8-25 
ODT object 1-1 
Operand 
Syntax 1-3 


p 


pointer 1-4 
pointer/name resolution addressing instructions 4-1 
process management instructions 18-1 
program 
execution instructions 9-1 
Management instructions 8-1 
program creation control instructions 10-1 
program entry procedure 9-7, 9-35 


Q 


queue management instructions 12-1 
queue space management instructions 15-1 


R 


relative instruction number 1-4 
resource management instructions 18-19 
resultant conditions 1-3 


Ss 
Scalar 1-3 
signed binary 1-1 
simple operands 1-1 
space addressing instructions 5-1, 5-3 
Space management instructions 6-1 
space pointer 1-4 
static storage 9-3 
static storage initialization 9-3 
Syntax definition 
array 1-4 
Character 1-3 
data pointer 1-4 
data pointer defined scalar 1-4 
instruction definition list element 1-4 
instruction number 1-4 
instruction pointer 1-4 
Numeric 1-3 
pointer 1-4 
relative instruction number 1-4 
Scalar 1-3 
space pointer 1-4 
space pointer data object 1-4 
system pointer 1-4 
variable scalar 1-4 
system pointer 1-4 


U 


unsigned binary 1-1 


V 

variable scalar 1-4 

Vital Product Data (VPD) 22-17 
VPD (vital product data) 22-17 


Index 
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